0

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?

closed as primarily opinion-based by Robert Harvey, gnat, Ixrec, durron597, user22815 Sep 19 '15 at 21:17

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise. If this question can be reworded to fit the rules in the help center, please edit the question.

  • As an aside, after reading 3-4 questions about commenting on this site, I'm left with a divided very non-unanimous opinion on the matter: To comment or not to comment, that is the (borderline-religious) question. Comment. Don't comment. No one agrees on the matter. I suppose it's a question you ask your project manager when you start and accept whatever the answer is. – Viziionary Sep 19 '15 at 1:29
  • 3
    No, project managers don't get to dictate that. – Telastyn Sep 19 '15 at 1:44
  • @Telastyn - I respectfully disagree. They do , and if in your case they don´t - then they should . Read my answer . – Obmerk Kronen Sep 19 '15 at 7:25
  • 2
    @ObmerkKronen Your answer appears to be based on the premise that "programmers" are bad at programming yet their bosses are good at programming. This may be true in some companies, but it's definitely not true where I work. I'm with Telastyn that there are much more important things to worry about than "comment consistency", and that "project managers" don't necessarily have any special authority on the matter. – Ixrec Sep 19 '15 at 11:20
  • 2
    @ObmerkKronen - you have a distorted view of the role project managers have in most organizations. – Telastyn Sep 19 '15 at 13:19
4

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.

  • 3
    Practising self documenting code is the key. Explaining the intent of the code out loud to myself and using those words in the method names and variable names really helps me – Sam Holder Sep 19 '15 at 11:34
3

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.

  • You sort of wrote what I commented reflectively. – Viziionary Sep 19 '15 at 1:31
-5

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 code maintainer) must fill that persons shoes , meaning to read all the past code and everyone will ALWAYS understand it . Then commenting is the 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 .

  • With respect, things like phpdoc, javadoc etc are not about commenting, they are about documenting your public api, not about commenting on the code inside your methods. There is a big difference. Documentation is important for consumers to be able to easily use you libraries (ie msdn). Comments in the code can be made virtually redundant by changing the structure of the code so it is more self documentation. See the 'clean code' movement. IMHO if you are a boss you should be telling your programmers to change how they code so the code is cleaner, not telling them to comment everything. – Sam Holder Sep 19 '15 at 11:30
  • @SamHolder first - I gave an example of phpdoc only because of it´s de-facto standard status, and not related to it´s purpose. it i still qualifies as code commenting. second do notice I did not made a difference between types of comments - you did that judgment. Third - you are assuming that all coders are as good as yourself. in a real world scenario that is simply not true. commenting code can help the less enabled coders to understand the process of a more enabled one . In a company of 100+ programmers , that is important. I guess those are conclusions that come with experience. .. – Obmerk Kronen Sep 19 '15 at 11:37
  • @SamHolder - and BTW - I would like to know how can you really debug code on a green-screen CNC machine or PLC , in a factory or a plant , without syntax highlighter and without comment blocks.... – Obmerk Kronen Sep 19 '15 at 11:39
  • I'm stating that code documentation and comments are very different, and to group them together is wrong. Even if you wrote great clean chide with no comments you may still need extensive documentation. And I stand by my statement that if you are encouraging your devs to comment (not document) the code then you are only adding to the problem. You should instead do code reviews and pair refactoring sessions to clean the code and remove to need for the comments. Otherwise how will any of your guys and girls get any better? – Sam Holder Sep 19 '15 at 11:45
  • 4
    Quit micromanaging. Commenting code isn't a high level requirement - quality software is a high level requirement, maintainable code is a high level requirement. Comments are a means to an end, and as a boss, you should get used to letting your experts determine the best way to get there. – Telastyn Sep 19 '15 at 13:15

Not the answer you're looking for? Browse other questions tagged or ask your own question.