[erlang-questions] dialyzer output help

[Roelof Wobben]

Op 10-8-2015 om 17:32 schreef Fred Hebert:
> I wanted to comment here on specific points, so I've taken your email 
> apart and reassembled it for what I felt fit a better narrative for my 
> stuff. Please don't see some dishonesty in the argument there 
> (creating a strawman or whatever) as this isn't my intent :)
>
> On 08/10, Garrett Smith wrote:
>> Back to comments - my point is that your *code* is the docs, as far as
>> implementation. If your code is not clear, make it clear. If you can't
>> make it clear, try harder. There are some very rare cases where some
>> code is just hard and some comments can help clarify what's going on -
>> but these are *unicorn rare* in my experience.
>>
>
> I've conducted a poll a few years ago (2012) on Erlang and Maintenance 
> in this community 
> (http://ferd.ca/poll-results-erlang-maintenance.html) and one of the 
> interesting results was in the following image (also attached):
>
> http://ferd.ca/static/img/charts/correlations_comments-erlang.png
>
> The idea that comments are not required tends to decrease with 
> experience in the language and familiarity with it. At the very least, 
> there was decent correlation.
>
> I like to think of it as someone learning to read: you first start by 
> reading out loud as you read; it helps build connections and solidify 
> your grasp on language. As you get a more profficient reader, you 
> subvocalize more and more up to the point where speed readers do not 
> even 'mentally read' words -- they just glance over the text and can 
> understand meaning from it anyway.
>
> Newcomers writing comments in the code, as far as I can rationalize 
> it, tends to be about writing down a translation of what the code 
> should be doing against the actual implementation.
>
> As you get more familiar, that translation takes place automatically 
> and the comments become more useless.
>
> If I had to give a tip to newcomers, it would be that it's fine to 
> write these comments first -- they act as a bit of a specification or 
> pseudo code. As you go on, the refactoring Garrett mentions would be 
> to try, as much as possible, to make the logic in your code look like 
> the comments you wrote, so that they become obsolete and can be dropped.
>
> Let's take some fake code as an example:
>
>    %% Verify that only adults (18 years or older) can enter
>    can_enter(Age) when Age >= 18 -> true;
>    can_enter(_) -> false.
>
> So that's a decent specification, and a newcomer gets to go "oh okay, 
> Age is the variable, >= is how they compare here, not =>, and 
> apparently the clauses are alternatives".
>
> As you get more used to it, you lose the interest for the comment, but 
> there's still a lot of interesting stuff left untold:
>
> - The function assumes that age is the accepted factor for adulthood
> - The function assumes that the program runs in a jurisdiction where 
>  adulthood is defined as 18, rather than 16, 19, or 21, for example, 
> or  that - The function only expects numbers to be passed in.
>
> So a more complete form could be imagined to be written like:
>
>    %% Age of adulthood in Quebec
>    -define(ADULT_AGE, 18).
>    -type age() :: number().
>
>    %% Age verification is required by the government
>    %% on online betting websites; credit cards would work
>    %% but can sometimes be granted to minors and isn't sufficient
>    %% for proper verification. However, just asking for age
>    %% can legally be considered good enough.
>    -spec can_enter(age()) -> boolean().
>    can_enter(Age) when Age >= ?ADULT_AGE -> true;
>    can_enter(_) -> false.
>
> And now the code has more criteria encoded. You'll noticed I pulled a 
> bunch of information out of my rear end just to add comments, but 
> really, those are the tricky things in code that bite us and are worth 
> putting in there, on top of everything else.
>
> Why? Because the next time someone comes in and refactors, they know 
> why the code was added, and it makes it so, so much easier to make a 
> good decision on whether it should be removed or not without having to 
> hope it's somewhere in source control.
>
> What should be kept in comments? The stuff that is hard to represent 
> in code:
>
> - Why you picked a given algorithm or implementation details
> - Gotchas are how to use the code
> - Edge conditions that cannot be represented otherwise (through type 
>  specifications and whatnot) in your language of choice
> - The rationale for broader design decisions. "We picked UUIDs for
>  identifiers because the system requires sharding and it is easier
>  with them than sequential ids" Hell: should the ids be considered
>  opaque or not?
>
> Details about what the code *does* are interesting to newcomers, 
> still, so part of the question you have to ask yourself is: who is my 
> target audience? Who will read this code?
>
> Even if the need is not there for veteran Erlangers, it might be there 
> for newcomers. If you're the senior member (or consultant) on a team 
> with a lot of new people, it might be interesting to put these 
> 'useless' comments in to onboard everyone else.
>
> Development is extremely human, and knowing that such comments are 
> important to some people means that they *should* be in your toolbox 
> if you work with them, or want them to work with you.
>
>> Documenting user facing functions, on the other hand, is important to
>> help your users understand how to use a function. It doesn't
>> necessarily cover each and every implementation detail - for that you
>> can always read the code - but it should provide what a user needs to
>> use the function as it was intended to be used.
>>
>
> Yes! But "read the code" is a pisspoor thing to tell almost *anyone*.  
> The reason is that there are many types of documentation for different 
> audiences:
>
> Newcomers: what does it do, why did you write it, who should or 
> shouldn't use this piece of code, where can additional info be found, 
> short examples, etc.
>
> Regulars: Reference manuals, examples, edoc, wikis, websites, api 
> descriptions
>
> Contributors: architecture, project structure, principles guiding the 
> design ("we favor the users on errors", "the state on disk cannot be 
> left inconsistent and we prefer to lose data", etc.), tests: where to 
> find them and how to run them, issue tracker, **the source**.
>
> If anyone but a contributor (or someone looking for contributor-level 
> information) has to read the source, your doc is not good enough.
>
> Regulars and newcomers shouldn't have to care about your code and how 
> it does things; they care about whether they should use it, what it 
> does, and how to use things.
>
> Only contributors or people debugging your stuff tend to care about
> *how* it does things or *why* it does it.
>
> I did expand a bunch on this in a blog post before, so I'll just link 
> to it rather than filling everyone's mailboxes even more: 
> http://ferd.ca/don-t-be-a-jerk-write-documentation.html
>
> Regards,
> Fred.
>

Thanks,

I will try to do this one my next assignment where i working now.

Roelof



---
Dit e-mailbericht is gecontroleerd op virussen met Avast antivirussoftware.
https://www.avast.com/antivirus