Comment style: Imperative or third person

coding-stylecomments

I have a question relating programming and english language both: Whether to use third person or imperative when commenting single lines of code.
Assume following line of code in a imperative language which should be commented:

object.doSomething();

My approach to comment this line would be to put the comment behind it using third person like this would be a ordinary english sentence containing the line as subject:

object.doSomething(); // does (referencing to the line of code) some action

But since we are in a imperative language and thus actually "commanding" the computer, one could even think of putting the comment before the code and using imperative:

//Do some action:
object.doSomething();

This is even useful when one need to comment multiple lines related to each other.

I personally prefer the first style but i often feel unsure about what style to use. It would be great if some could write their personal experience down here.

Best Answer

Oracle's official style guide states:

Use 3rd person (descriptive) not 2nd person (prescriptive). The description is in 3rd person declarative rather than 2nd person imperative.

Gets the label. (preferred)

Get the label. (avoid)

Oracle's style guide can be found here.

Related Solutions

What’s a quick way to comment/uncomment lines in Vim

For those tasks I use most of the time block selection.

Put your cursor on the first # character, press CtrlV (or CtrlQ for gVim), and go down until the last commented line and press x, that will delete all the # characters vertically.

For commenting a block of text is almost the same:

First, go to the first line you want to comment, press CtrlV. This will put the editor in the VISUAL BLOCK mode.
Then using the arrow key and select until the last line
Now press ShiftI, which will put the editor in INSERT mode and then press #. This will add a hash to the first line.
Then press Esc (give it a second), and it will insert a # character on all other selected lines.

For the stripped-down version of vim shipped with debian/ubuntu by default, type : s/^/# in the third step instead (any remaining highlighting of the first character of each line can be removed with :nohl).

Here are two small screen recordings for visual reference.

Comment:

Uncomment:

Xml – How to comment out a block of tags in XML

You can use that style of comment across multiple lines (which exists also in HTML)

<detail>
    <band height="20">
    <!--
      Hello,
         I am a multi-line XML comment
         <staticText>
            <reportElement x="180" y="0" width="200" height="20"/>
            <text><![CDATA[Hello World!]]></text>
          </staticText>
      -->
     </band>
</detail>

Best Answer

Related Solutions

What’s a quick way to comment/uncomment lines in Vim

Xml – How to comment out a block of tags in XML

Related Topic