Consistency is something I value (at an OCD perfectionist level to be honest). I can live with not writing any comments and focus on producing good, refactored, readable code -- or, if I must comment, I would prefer to decide on a very specific comment pattern and comment in that way throughout the entire code consistently, not just to explain certain complicated parts.
Is commenting everything as described or not at all, but not "somewhere in between" an acceptable coding practice?
At my first real job I was hired by a couple of OCDers who wanted me to always write code like this:
/* comment describing what the next few lines do */
a line of code
a line of code
a line of code
/* comment describing what the next few lines do */
a line of code
a line of code
a line of code
etc.
The idea was that it should be possible to gain a relatively good understanding of what the code does by reading through the comments, completely disregarding the actual code. For this to work there were some additional rules, for example that code comments always had to begin with a verb, etc.
So, I learned to program this way, and I thought it was cool. Unfortunately, this led to many WTF situations, like the following:
function int foo( int x )
{
/* preconditions */
assert x > 0;
/* change state */
this.x = x;
/* return same value to enable fluent style */
return x;
}
At jobs that I did after that, people either looked at my coding style and did not say anything in order to avoid insulting me, or, if they felt friendly enough to give me advice, they told me that this style of commenting was moronic.
Furthermore, other programmers did not feel obliged at all to follow my style of commenting, so when someone else amended my code, their complete disregard towards my comments was often tantamount to subversion, for example:
/* return same value to enable fluent style */
notifyTheWorldThatXHasChanged();
return x;
So, in my experience, in most workplaces out there, this style of commenting tends to be frowned upon.
My advice would be to write self-documenting code and follow the "minimal comments" rule, which means only add a comment if it is necessary. Comments in code should only be needed in exceptional circumstances, and their presence should alert the reader that there is something extraordinary going on.
When is a comment necessary? When a reasonably careful reading of the code does not reveal what the code does, or why a certain thing is done in a particular way.
What should be considered a reasonably careful reading of the code? It is when you focus all of your attention to reading the code, with an honest aim to understand what it does, but you trust that the code actually does what it appears to aim to do, so you are not actually going through the pain of executing the code in your mind, trying to figure out what it really does, as if the code has ulterior motives. You should only have to do that when debugging code.
Of course, the trick is to write that elusive self-documenting code which, when you look at it, its aim becomes readily obvious. I like to believe that what we do is mostly a science, but this particular little bit seems more like an art to me. An art well worth mastering.
Acceptable to whom?
If your boss will fire you because you were inconsistent in your comments, it is maybe not acceptable. If your boss fires you because you went OCD with the comments rather than shipping, it is maybe not acceptable.
Consistency in comments is... Okay I guess. Consistency in code is better. Consistency in tests is better. Consistency in process is better. And good comments, good code, good process, and good tests are better than consistently bad stuff.
So the question about if it is acceptable or not is rather moot, because nobody much cares about it.
First , as @Telastyn wrote , your question is rather subjective .. Also , it seems that the problem is not with your boss / company / team / world-standards , but internally yours.
As such, I can only give my two cents ( read : opinion ) on the matter .
This answer was heavily edited after I was educated ( by the kind users ) on the merits on non-commenting . Never. In any situation . in any language. in any tool .Even if it stands on the way of my instincts as a programmer to predict unpredictable situations. In this case - there are none. Everyone will always understand my code which will always be on top-zen level and maintained by me.
Commenting is Crucial .
Comments are awful. You should NEVER use them . use ZEN .
I was a programmer in the past . Today I am the Boss .
This has given me two a very different perspectives on the matter .
As a programmer, you do not really understand why you always need to comment. seems a waste of time . I mean, I know my own code , right ?
Well - not always . Try going back to some obscure code that you yourself wrote 15 years ago in a language you maybe not use as frequent as you did - and suddenly you wish you were commenting better ...
Today, after a lot of years, I comment every function even before I write the function itself.
( small edit : take a look at this answer I just found )
.
As a Boss ( or owner of a company ) - commenting is a high level not a requirement, for the simple reason that today, the staff and employees has little , if not none , fidelity to the workplace . they can quit the job on a day´s notice ( or no notice at all ) , or simply get fired for any one reason , Or in more extreme cases , something bad could happen ( accident , sudden sickness, even death - its part of life ) and then someone else ( called a everyone will ALWAYS understand it . Then commenting is code maintainer) must fill that persons shoes , meaning to read all the past code andthe only rescue at hand NOISE .
If you are looking for a world defined standard for commenting, you will probably wont find it ( although there are language-specific ( like PHPdoc ) and even project-specific standards ) . Because honestly , I was thought it should not exist.
If you are looking for an answer on if to comment or not - I say Yes Defiantly no!. Comment as much as noise you can get.
If you are looking for an answer on what or where to comment - you will have to .use your common sense and find it yourself. Just stop commenting - thus constructing some kind of personal standard for your future work. ( this is what I eventually did ).
.. and if you are looking for an answer for your direct question "all or nothing" - than IMHO all is better then nothing Nothing is always better, but still - common sense not commenting option is your best friend .
