[erlang-questions] Which choice is better? Function or Case

[Michael Truog]

On 03/09/2013 01:17 PM, Joe Armstrong wrote:
>
>
> On Sat, Mar 9, 2013 at 3:13 PM, Henning Diedrich <hd2010@REDACTED <mailto:hd2010@REDACTED>> wrote:
>
>     Hi list,
>
>     I realize I keep coming back to the question, even on Saturdays, did Gianfranco mean more comments, or less.
>
>     On Mar 8, 2013, at 1:54 PM, Gianfranco Alongi <gianfranco.alongi@REDACTED <mailto:gianfranco.alongi@REDACTED>> wrote:
>
>     > Therefore, minimize the time needed to read your code, making it cheaper.
>     >
>
>
>     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.
>
>     While the language already offers different ways to achieve the same thing, how much more liberty is there in commenting.
>
>     Robert one time suggested the Church of Short Variable Names to me as a way to reduce Erlang's occasional verbosity.
>
>     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.
>
>     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.
>
>
> 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. 
>
> Also comments should be extremely accurate . Non-obvious tricks should be
> explained in detail. Obvious things should not be commented.
>
> Comments should be repaired with the same lova and care as code. Without
> spelling and punctuation errors. If I see a typo in a comment my brain says
> "this program is not yet ready for publication" - practising the art needs fine
> attention to detail. 
>
> I actually think one should publish (for each module)
>
>     - a .hrl file for each module with comments and function specs and types
>     - documentation for the module
>     - a .beam file
>  
>     and NO .erl file (should be available on demand)
>
>     Doing this would really test if you code is sufficiently well described for
> somebody else to actually use.
>
>    If somebody has to read your code to figure out what it does you have failed.
>
>    (This is yet another reason why programming is difficult and takes time)
>
> Cheers
>
> /Joe

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.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20130309/c47dfbed/attachment.htm>