Up to Main Index                               Up to Journal for May, 2012

                     JOURNAL FOR THURSDAY 17TH MAY, 2012
______________________________________________________________________________

SUBJECT: Commenting about [code] comments...
   DATE: Thu May 17 20:59:25 BST 2012

Still going through and writing documentation for all the code I've written so
far. Then I thought 'what is the idiomatic way of commenting in go?'.

When writing Java, C - hey! I learned K&R style :) - and more recently PHP
*grumble* I'd use:


                  /**                          /*
                   * blah blah                  * blah blah
                   * blah blah        OR        * blah blah
                   * blah blah                  * blah blah
                   */                           */


Checking the Go Language Specification it says:


  There are two forms of comments:

     1. Line comments start with the character sequence // and stop at the end
      of the line. A line comment acts like a newline.

     2. General comments start with the character sequence /* and continue
        through the character sequence */. A general comment containing one or
        more newlines acts like a newline, otherwise it acts like a space.

     Comments do not nest.


Then in Effective Go it says:


  Go provides C-style /* */ block comments and C++-style // line comments.
  Line comments are the norm; block comments appear mostly as package comments
  and are also useful to disable large swaths of code.


It even has an example like:


  /*
    blah blah
    blah blah
    blah blah
  */


With a comment that "Comments do not need extra formatting such as banners of
stars". OK so that's the style I used. Then I read a post on the golang-nuts
mailing list where according to Andrew Gerrand:


  Idiomatic Go comment style is:

  // blah blah
  // blah blah
  // blah blah


Looking at a large number of go sources for the standard library I see that,
yes everything is written like that. Oh bum :(

However while switching style I found that Vim didn't like reformatting blocks
of line comments very well. Using my normal 'gqq' it kept grabbing code that
followed and reformatted that as well unless I manually selected the block. So
I came up with a little incantation that lets me hit F9 in a block and
reformat it:


  nmap <F9> :.?\v^$\|^[^/]?+1;//-1 !par p3w80<CR>


This works OK, but not if the comment block starts on the first line of a file
or ends on the last line. Not a big problem and something I can look into
later.

As you can see from the w80 I try and keep code to a width of 80 characters.
Why? We have massive screens these days I hear you cry! Yes, my terminal is
usually 278x79 or 212x77, sometimes only 80x25. When using Vim I usually work
with multiple files open and having them side by side is very convenient.

--
Diddymus


  Up to Main Index                               Up to Journal for May, 2012