in reply to Programming *is* much more than "just writing code".
++ for your thoughtful insights.
I dislike coming across code that is more comment than code.
I disagree though, that just because we can't be expected to make up for deficiencies in the knowledge or those that follow us in maintenance, that that is reason to comment tersely or not at all.
A programmer, especially a skilled one, can hold a great many variables in their head at once. And a programmer using a succinct language such as Perl can produce a mountain of functionality from a few lines of code - that often can't be written more clearly even if it is spread across more lines of code. A maintenance programmer coming in later will have to absorb all of the variables, and all of the logic - JUST to get an idea of what is going on in a local area. Code split into paragraphs with simple discriptive comments at the top of each paragraph are easy to digest and figure out what is going on. They are also potentially search able.
Looking at some code I wrote six months ago I came across the following "code paragraph headings:"
I was able to dive right in to what is going on with the code without reading any code. Each of those comments are around a section of code of 5 to 10 lines each that I COULD figure out if I wanted to. But I didn't have to expend the thought to do so.
Now, one important thing, is that you cannot account for programmers who lie or who comment incorrectly - but it becomes obvious quickly which comments don't correlate at all.
So I would add some additional addenda to your conclusions:
No programmer can expect to account for all maintenance programmer shortcomings, but that does not free you from the obligation to try.
More often-than-not you are the maintenance programmer.
Keep your logic in discrete logical chunks with defined purpose - defined either with a comment or in external documentation.
Some code requires no comments.
No amount of documentation (too much, too little, or just right) will ensure that the maintenance programmer will read your documentation. Use comments and documentation.
I dislike coming across code that is more comment than code.
I disagree though, that just because we can't be expected to make up for deficiencies in the knowledge or those that follow us in maintenance, that that is reason to comment tersely or not at all.
A programmer, especially a skilled one, can hold a great many variables in their head at once. And a programmer using a succinct language such as Perl can produce a mountain of functionality from a few lines of code - that often can't be written more clearly even if it is spread across more lines of code. A maintenance programmer coming in later will have to absorb all of the variables, and all of the logic - JUST to get an idea of what is going on in a local area. Code split into paragraphs with simple discriptive comments at the top of each paragraph are easy to digest and figure out what is going on. They are also potentially search able.
Looking at some code I wrote six months ago I came across the following "code paragraph headings:"
### check if we are in the delete grace period ### adjust check time if the last order was a renew or a transfer ### determine what the status will be if there are no errors
I was able to dive right in to what is going on with the code without reading any code. Each of those comments are around a section of code of 5 to 10 lines each that I COULD figure out if I wanted to. But I didn't have to expend the thought to do so.
Now, one important thing, is that you cannot account for programmers who lie or who comment incorrectly - but it becomes obvious quickly which comments don't correlate at all.
So I would add some additional addenda to your conclusions:
No programmer can expect to account for all maintenance programmer shortcomings, but that does not free you from the obligation to try.
More often-than-not you are the maintenance programmer.
Keep your logic in discrete logical chunks with defined purpose - defined either with a comment or in external documentation.
Some code requires no comments.
No amount of documentation (too much, too little, or just right) will ensure that the maintenance programmer will read your documentation. Use comments and documentation.
my @a=qw(random brilliant braindead); print $a[rand(@a)];
In Section
Meditations