Beefy Boxes and Bandwidth Generously Provided by pair Networks
We don't bite newbies here... much
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??
I almost have to assume that you misinterpret this on purpose, possibly to point out that I wasn't very exact in my post. In any case:

You are confusing "how comments" and "what comments". In the example taken from Refactoring, you don't seriously believe that the name of the new sub should describe how the code works? No, it describe what it does, and what it is for. That should be pretty obvious.

Then for most code, especially in small blocks with good names, it should be quite clear what is happening from just reading the code - some people even advocate that if the code is well-written, it should not need any comments whatsoever. That I can't really agree on, there are always hairy parts that needs extra explaining. And as someone once said: "Good code has lots of comments, bad code needs lots of comments." - meaning that you should always comment your code, no matter which of them you write... especially since who are you to tell? :)

You think that it is somehow mutually exclusive with comments and verbose names. Why? Where did I say that you can't explain your data structure because you have a good name? The name is there so you can see what data is being worked on in the code, not so you can see how. That either is easy enough to read from the surrounding code, or is documented somewhere where it is easy to find.

Again, how contra what.

Documenting the variables name once like thus:

# Holds all employees names my @em;
instead of naming it something like:
my @employee_name;
is your choice then? Well, it is not mine. If I have a semisized piece of code, then I don't want to have to go to the top of the program (potentially) to find out what each variable holds, each time I encounter them. If I know what data is in it, from the name, then I can work on. If I don't know the data structure, and it isn't possible to (easily) deduce from the surrounding code, then I'll go look for some docs on the structure. What or how.

Perl programmers often pride themselves on "Laziness", since it is one of the programmer's virtues according to Larry Wall. Well, there is false laziness too. Trying to "save time" by typing a few less keys is definetely false laziness - at least if you are trying to hold that as a virtue. As the XP and refactoring people say about writing tests - you have the extra time for it, because you didn't really code all, or even most of the time that you sat at your computer anyways. As with tests, you can save a lot of maintenance and bug fixing by being clear about what happens. Even if apt naming isn't gonna do a big difference on its own, together the small things count. Beware of false laziness.


You have moved into a dark place.
It is pitch black. You are likely to be eaten by a grue.

In reply to Re(3): Of variable {mice} and its name {man}. by Dog and Pony
in thread Of variable {mice} and its name {man}. by vladb

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others perusing the Monastery: (7)
    As of 2014-09-18 10:18 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      How do you remember the number of days in each month?











      Results (110 votes), past polls