When I watch programming video tutorials I noticed that different people (native EN speakers) use different styles of commenting the code when it comes to articles.

Some use the headline style without article and capitalizing every word like:

<!-- Code To Set Right Block Color -->
background-color: red; 

and some write it as a normal text:

<!-- The code to set the right block color -->
background-color: red;

My question is which of these two comment styles (or some other?) is more appropriate when commenting programming code when taking English rules into account ?

closed as primarily opinion-based by tchrist, MetaEd, Kris, Andrew Leach, Kristina Lopez Jul 10 '13 at 17:46

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.

  • 2
    Depends on who's going to read it. If it's only you, use any style you like. If somebody else is going to need to understand it, that's a different matter. Who? And what do they need to know first? – John Lawler Jul 9 '13 at 20:25
  • 3
    There is simply no answer to this. Appropriate by whose standards? – Colin Fine Jul 9 '13 at 20:40
  • Better asked on SO for a useful and pragmatic answer. – Kris Jul 10 '13 at 7:46

I would say use of the headline format is appropriate for defining the purpose of a section of code. The following would be an appropriate use of the headline style.

#nav:hover {
    /* Code to Render the Hover State */
    background: red;
    border: 1px solid black;
    color: white;

However, as in your example, if the comment refers to a single line, a headline makes less sense, i.e., if you aim to rephrase code in English form, it ought to be a full statement. Thus I would recommend the following.

#nav:hover {        
    background-color: red; /* Provide a rule to set the right block color. */
  • Headlines themselves are increasingly appearing in running format these days. No reason to stick to tradition. – Kris Jul 10 '13 at 7:29

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