Advertisement
If you have a new account but are having problems posting or verifying your account, please email us on hello@boards.ie for help. Thanks :)
Hello all! Please ensure that you are posting a new thread or question in the appropriate forum. The Feedback forum is overwhelmed with questions that are having to be moved elsewhere. If you need help to verify your account contact hello@boards.ie

Code Comment Best Practice

Options
13»

Comments

  • Options
    #62
    Duggys Housemate
    Closed Accounts Posts: 3,298 ✭✭✭Duggys Housemate


    GreeBo wrote: »

    Are you printing out code or something?
    Who cares if the source code is large because it has comments in it...am I totally missing your point here? Whats the issue?

    Yeah. Clean code means smaller functions.

    No I am not printing it out, I am reading it. The longer the function or method the less clean the code.

    Nobody has yet explained to me why normal code - a for loop, an if statement etc. - needs to be commented if the variables are verbose, and strongly typed.


    And this, by the way is standard. Most books in clean code writing argue against comments in the blocks.

    Explain the odd stuff. You are admitting your code is obstufcated if it is over-commented.


  • Options
    #63
    Duggys Housemate
    Closed Accounts Posts: 3,298 ✭✭✭Duggys Housemate


    Also if you do feel the need to comment a for loop ( this loops parses a comma delimited string for 'bob' ) you should think about refactoring into a function called parseCommaDelimitedStringForBob and comment that.


  • Options
    #64
    GreeBo
    Registered Users Posts: 27,161 ✭✭✭✭GreeBo


    Duggys Housemate wrote: »
    Yeah. Clean code means smaller functions.

    No I am not printing it out, I am reading it. The longer the function or method the less clean the code.

    Nobody has yet explained to me why normal code - a for loop, an if statement etc. - needs to be commented if the variables are verbose, and strongly typed.


    And this, by the way is standard. Most books in clean code writing argue against comments in the blocks.

    Explain the odd stuff. You are admitting your code is obstufcated if it is over-commented.
    So read the comment, then read the code, if you need to.
    You must hate the Java Api so, its probably at least 50% comments.

    Clean doesnt mean clear of comments; at least not to me it doesnt.

    Nobody has explained it because nobody is advocating you comment simple/basic/normal code structures, unless they are doing something abnormal, perhaps you should try re-reading the comments in this thread... ;)


  • Options
    #65
    Sparks
    Registered Users Posts: 40,038 ✭✭✭✭Sparks


    DH, I think your problem here is not whether or not there are comments; but whether or not those comments make it easier to read the code. Thing is, if they don't, they're not examples of good commenting and shouldn't make it past code review anyway; but that doesn't mean the idea of a comment block at the top of nontrivial code blocks (whether those blocks be functions or parts of functions or any other code subdivision you care to mention) is a bad one; just that whomever wrote the comments did so badly.


Advertisement