<br><br><div class="gmail_quote">On Sat, Mar 9, 2013 at 3:13 PM, Henning Diedrich <span dir="ltr"><<a href="mailto:hd2010@eonblast.com" target="_blank">hd2010@eonblast.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Hi list,<br>
<br>
I realize I keep coming back to the question, even on Saturdays, did Gianfranco mean more comments, or less.<br>
<div class="im"><br>
On Mar 8, 2013, at 1:54 PM, Gianfranco Alongi <<a href="mailto:gianfranco.alongi@gmail.com">gianfranco.alongi@gmail.com</a>> wrote:<br>
<br>
> Therefore, minimize the time needed to read your code, making it cheaper.<br>
><br>
<br>
<br>
</div>In likeliness, I fancy, you meant neither and the balance between cluttering the source into unreadability or under commenting is as delicate as the coding itself.<br>
<br>
While the language already offers different ways to achieve the same thing, how much more liberty is there in commenting.<br>
<br>
Robert one time suggested the Church of Short Variable Names to me as a way to reduce Erlang's occasional verbosity.<br>
<br>
Once you dare writing one-letter variables, it makes a difference like night and day. It is, on the face of it, so much easier to read.<br>
<br>
But using single letter variables all but makes comments part of the code. One may claim the code to be close to useless without the comments.<br></blockquote><div><br></div><div>I try to use very short variable names. In my mind variable names carry to meaning. I'm very very fussy about extremely accurate function names. If a function says do_this_and_that it should do exactly this_and_that and not something else. </div>
<div><br></div><div>Also comments should be extremely accurate . Non-obvious tricks should be</div><div>explained in detail. Obvious things should not be commented.</div><div><br></div><div>Comments should be repaired with the same lova and care as code. Without</div>
<div>spelling and punctuation errors. If I see a typo in a comment my brain says</div><div>"this program is not yet ready for publication" - practising the art needs fine</div><div>attention to detail. </div><div>
<br></div><div>I actually think one should publish (for each module)</div><div><br></div><div>    - a .hrl file for each module with comments and function specs and types</div><div>    - documentation for the module</div>
<div>    - a .beam file</div><div> </div><div>    and NO .erl file (should be available on demand)</div><div><br></div><div>    Doing this would really test if you code is sufficiently well described for</div><div>somebody else to actually use.</div>
<div><br></div><div>   If somebody has to read your code to figure out what it does you have failed.</div><div><br></div><div>   (This is yet another reason why programming is difficult and takes time)</div><div><br></div>
<div>Cheers</div><div><br></div><div>/Joe</div><div> </div><div><br></div><div><br></div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
Since we just saw specs evolving from comment annotations to language part, I wonder if that is a pointer:<br>
<br>
what part of the comments are to be considered mandatory part of the code, beyond specs, which latter had type verification as focus.<br>
<br>
What other commenting part that has semantics as focus would emerge, not to create new restrictions but as a guide line to support one's future self, or whoever inherited your code?<br>
<br>
This, in part, goes back to Joe's proposal to annotate the Internet. While that was not about form but more of a technical discussion, the inspiration is similar.<br>
<span class="HOEnZb"><font color="#888888"><br>
Henning<br>
<br>
<br>
<br>
</font></span></blockquote></div><br>