<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div class="moz-cite-prefix">On 03/09/2013 01:17 PM, Joe Armstrong
wrote:<br>
</div>
<blockquote
cite="mid:CAANBt-o5pYO5ehgsAUhAjsxf74msxJRj9_Kwy4Aj3oMj7xrO5g@mail.gmail.com"
type="cite">
<meta http-equiv="Context-Type" content="text/html;
charset=ISO-8859-1">
<br>
<br>
<div class="gmail_quote">On Sat, Mar 9, 2013 at 3:13 PM, Henning
Diedrich <span dir="ltr"><<a moz-do-not-send="true"
href="mailto:hd2010@eonblast.com" target="_blank">hd2010@eonblast.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote">
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
moz-do-not-send="true"
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>
</blockquote>
<br>
I think the only major annoyance with what you have suggested with
.hrl files is that edoc does not operate on the comments within .hrl
files, so the functions are left missing from the documentation that
edoc generates. I have not looked at what it would take to get edoc
to work with .hrl files, but I assumed it was a lower layer throwing
the comments out before edoc gets them.<br>
<br>
</body>
</html>