Documentation blocks are a good thing though, no matter how small the method. Means you can understand an API or purpose of a class without even looking at the code to figure out what it's trying to do. Means nice web manuals basically.
Documentation is static, it cannot be compiled and gets out of date pretty fast (unless you are in a vertical hierarchy where five people need to accept a change before you are allowed to checkout and commit a one-line modification). With a good method name and good argument names you can understand what the method does, and if you can't the method is probably too large still for its own good.
Personal opinion but it's far better to have a set of unit tests working as a live documentation which can be compiled and executed (for example, having a
BlowfishEngineReleasesSboxTables_WhenDestroyed method or a
GivenABlowfishEngine_WhenDestroyed_ThenReleasesSboxTables if you are into
BDD, or naming the test class as
BlowfishEngineTests or
BlowfishEngineUnitTests,
BlowfishEngineShould or my favorite,
BlowfishEngineMust with the method just called
ReleaseSboxTables_WhenDestroyed). This way the documentation exists in the class and method names, like
BlowfishEngineMust.ReleaseSboxTables_WhenDestroyed,
BlowfishEngineMust.AllocateSboxTables_WhenCreated,
BlowfishEngineMust.ThrowException_WhenKeyIsInvalid,
BlowfishEngineMust.ReturnEmptyArray_WhenNoMatchesAreAvailable, etc, etc. And then you immediately know when the contract between the method name (or "documentation") and the compiled code is broken.
Mind you, this is 1996 code so I understand why every single method including empty, constructors and destructors are commented but I would think most companies are already past that. I think it's better to have a readable code where you know what it is doing than having to read the documentation and then check the code to see if it's still doing what the comment says it does.
github.com
.
