Love4Boobies wrote:Has your target audience never programmed before? If you need a verbose comment to tell you that "struct tcb *tcb = tcb_alloc();" tries to allocate memory for a TCB structure, you have no business writing code. Next, an
if statement that returns
NULL when
tcb_alloc fails---hmm, I wonder what that could mean... Better check the comment!
Such bad practice simply wastes development time for both the person who initially writes the code (since they need to type in the same thing twice) and the maintainers to follow, who need to read through the silly comments to get to the actual code---and then maintain them.
Maybe the "error" is to comment the task itself being performed by that line. It would be better to comment about ultimately why that is being done, with what purpose or intention. In this way, the thinking behind the code is more accessible, and it would be very useful, informative and educative even for someone planning to write a very different implementation in a completely different language (we are talking about actual implementation tricks more than raw concepts from a generic specification or document).
I once read that if a programmer doesn't care enough to keep the comments in the source code synchronized with the current code, then most certainly the overall quality of the code produced by that programmer will be equally poor and the programmer would be demonstrating carelessness (I would say that it could even be considered incorrect because if the comments help keep track of, for instance, tens of parameters to use and update very sligthly for different functions -in other words, a very error-prone thing-, it could lead to errors and even make coding too confusing for not needing to improve it).
What I do is an iteration between documentation and code. And when I code, I write down the ideas that appear fast in my mind in the form of codes, of what I will do next.
Then I write documentation and let the current code to become bulky, even with partially wrong lines of code commented out.
After I have a minimally useful program, I archive the whole current code in a ZIP file with the current date/time as its version number. Then I start cleaning up everything (outdated code, commented-out lines of code, inefficient code, some bugs, add some more code...).
Then I leave comments that explain how to use functions, but also group very similar functions with very small variations inside INIT-END blocks of comments (INIT and END are repeated at least in 3 consecutive lines and explaining briefly in 1 line what that block is for).
And then I keep comments for the major, overall, non-obvious parts/"sections" of the code and specially functions right from my most recent documentation. I do this because when I implement what I have documented, almost always many strange quirks start appearing in the code (so the explanation of the concepts from the documentation and the explanation of how to actually implement them are virtually two different things). That's why I leave comments, but at least I update and order them iteratively, and I also accompany my code with full human-readable documentation (of course, even accumulated from separated documents written and corrected over time, often directly useable for different projects) for the concepts and the implementation quirks.
Keeping a more human-readable code structure allows me to catch up on projects I have left for months and remember what I was doing faster in a more precise code section, and at least for me it's specially useful when I'm trying to learn very different things from one another.
