Writing Before Reading

  • Steve Jones - SSC Editor

    SSC Guru

    Points: 718992

    Comments posted to this topic are about the item Writing Before Reading

  • David.Poole

    SSC Guru

    Points: 75347

    One of the reasons I like Python is that one of its design goals is readability.

    I've always found SQL to be highly readable too.

    I really took Bob Martin's Clean Code book. https://www.amazon.co.uk/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882

    Following his approach can help you make your code easily read.

    I've mentioned before that although you write code to perform a desired action you can write it to be used as a teaching aid.

  • nicksamuel

    Valued Member

    Points: 67

    Wow! - I have learnt that there are names for some obvious tendencies and people have been researching some of them for decades. I have been further educated. (Now, I am just thinking of some of my friends' taste in music!)

    As a contractor, I often have to deal with other people's code (recently, 12,500 lines in one routine.) So I have got familiar with the unfamiliar. Sometimes I do reformat it (like in the case where the developer had put all the code in one line - no CRs anywhere) to help me understand the logic. Just the task helps as well as the result.

    I do look to learn - whether the previous developer has a usage or technique I would do well to use. So I hope I improve all the time but  the familiar, that is what we find easiest to remember and in which we feel most secure.

  • gvoshol 73146

    Hall of Fame

    Points: 3174

    nicksamuel wrote:

    ...

    Sometimes I do reformat it (like in the case where the developer had put all the code in one line - no CRs anywhere) to help me understand the logic. Just the task helps as well as the result.

    I do look to learn - whether the previous developer has a usage or technique I would do well to use. ...

    Yes, I've reformatted the code of others before attempting to debug or modify it.  Never encountered all the code in one line, but there's been quite a few cases of extremely long lines that I had to break up just so I didn't have to continuously scroll back and forth.

    Sometimes it's really a head-scratcher: "What the heck was he trying to do here?"  And sometimes after I figured it out, like you, I found a technique to use.  Other times I found a technique to avoid at all costs!

  • roger.plowman

    SSChampion

    Points: 10236

    There's a secret to reading code. 🙂

    Don't try.

    Or rather, do it only once. Code is called code for a reason. Even the best written code is not written for readability by humans. It's written to be efficient for the computer. So despite all the code-writing best practices (linear flow wherever possible, preflight check patterning, good variable names, constants instead of magic numbers, etc. ad nauseum)  code is still at best a (very) foreign language, one you will never be fluent in because there are as many "dialects" as there are developers.

    Which is why at our company we specify that wherever possible code requires 70% comments to 30% code. Of course those comments should be "why" not "how" comments, and it does take effort to maintain them and make sure code changes always have comment updates as well, but the end result is rapid comprehension because you read English, not code.

    Our company policy is to read the comments first, then quickly see if the code makes sense and matches the comments. If the code writer followed commenting best-practice it will. And having annotated code means having understandable code--without the need for analyzing the code. Much faster!

    Of course most developers HATE comments with a passion. They hold that well-written code doesn't need them, that well written code is self-documenting. Comments make the code too long and verbose, you can't see the code for the blasted comments. And 70% comments to 30% code???? Are you joking?

    Visual Studio supports code folding and code hiding. There's this nifty little extension called Remarker that lets you change comment size and color based on the type of comment. Comment headers can be normal size while comment bodies can be in a smaller font. You can then hide the comments by folding them away giving you the best of both worlds.

    SSMS is a little less flexible but since SQL is so antiquated anyway it pays to keep stored procedures simple. Even so anything of any complexity should still follow the 70% comment rule. Unless it's just a simple SELECT of course. But even then you should explain WHY the stored procedure exists.

    Follow comment discipline religiously and you'll find that at least in-house code doesn't have to be read--without a cheat sheet, at least! Even your own code will mystify you six-months later. Oh, and "well written code is self-documenting"? It's a LIE.

     

    c1

     

     

     

  • Jeff Moden

    SSC Guru

    Points: 996436

    +1 Billion to Roger Plowman for his post above.  I'll also add that commenting code when you're writing it is pretty simple.  The first thing I normally do is to write the comments of the things I need to get done and why.  That also creates a bit of a "functional plan" of what I need to do and then I fill in the code between the comments.

    Of course, you sometimes need to adjust the plan and the first thing you should do is adjust the comments and then fill in the code.

    I'll also state that doing comments this way really helps write code faster especially if you're frequently interrupted.  You don't have to ask yourself "Now where was I at and what the hell was I thinking" because it's in the comments.

    My rule for comments is "If you remove all of the code, the comments that remain should provide you with enough information to draw a functional flowchart".

    Unfortunately, it's becoming a lost art and companies pay dearly for it.

    --Jeff Moden


    RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
    First step towards the paradigm shift of writing Set Based code:
    ________Stop thinking about what you want to do to a ROW... think, instead, of what you want to do to a COLUMN.
    "Change is inevitable... change for the better is not".

    Helpful Links:
    How to post code problems
    How to Post Performance Problems
    Create a Tally Function (fnTally)
    Forum FAQ

  • Tom_Hogan

    Hall of Fame

    Points: 3565

    Jeff Moden wrote:

    ...The first thing I normally do is to write the comments of the things I need to get done and why.  That also creates a bit of a "functional plan" of what I need to do and then I fill in the code between the comments...

    Stealing this.

  • Jeff Moden

    SSC Guru

    Points: 996436

    Tom_Hogan wrote:

    Jeff Moden wrote:

    ...The first thing I normally do is to write the comments of the things I need to get done and why.  That also creates a bit of a "functional plan" of what I need to do and then I fill in the code between the comments...

    Stealing this.

    They say the highest compliment that can be paid is imitation.  Thank you for the compliment. 😀

     

    --Jeff Moden


    RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
    First step towards the paradigm shift of writing Set Based code:
    ________Stop thinking about what you want to do to a ROW... think, instead, of what you want to do to a COLUMN.
    "Change is inevitable... change for the better is not".

    Helpful Links:
    How to post code problems
    How to Post Performance Problems
    Create a Tally Function (fnTally)
    Forum FAQ

  • Steve Jones - SSC Editor

    SSC Guru

    Points: 718992

    Jeff Moden wrote:

    +1 Billion to Roger Plowman for his post above.  I'll also add that commenting code when you're writing it is pretty simple.  The first thing I normally do is to write the comments of the things I need to get done and why.  That also creates a bit of a "functional plan" of what I need to do and then I fill in the code between the comments.

    Of course, you sometimes need to adjust the plan and the first thing you should do is adjust the comments and then fill in the code.

    A lot of what you're specifying here is the idea of TDD. With the plan, having the results specified helps to ensure you're covering the requirements that you want to meet.

  • Rod at work

    SSC-Dedicated

    Points: 33359

    Great article, Steve! I've held to both NIH stance at times and the proudly found elsewhere stance at other times. I'm not sure which is right. Perhaps the extreme of both is wrong and somewhere in the middle is the best way to go.

    Kindest Regards, Rod Connect with me on LinkedIn.

  • Jeff Moden

    SSC Guru

    Points: 996436

    Steve Jones - SSC Editor wrote:

    Jeff Moden wrote:

    +1 Billion to Roger Plowman for his post above.  I'll also add that commenting code when you're writing it is pretty simple.  The first thing I normally do is to write the comments of the things I need to get done and why.  That also creates a bit of a "functional plan" of what I need to do and then I fill in the code between the comments.

    Of course, you sometimes need to adjust the plan and the first thing you should do is adjust the comments and then fill in the code.

    A lot of what you're specifying here is the idea of TDD. With the plan, having the results specified helps to ensure you're covering the requirements that you want to meet.

    Thanks for the feedback, Steve.   Heh... it's amazing what they end up calling things.  I've been doing this type of thing since I worked on old unit record equipment and punched cards starting way back in (IIRC) 1969.  The concept of "comments in code" obviously couldn't be applied but I always built a functional flowchart and a wiring diagram for the "program board" first.

    --Jeff Moden


    RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
    First step towards the paradigm shift of writing Set Based code:
    ________Stop thinking about what you want to do to a ROW... think, instead, of what you want to do to a COLUMN.
    "Change is inevitable... change for the better is not".

    Helpful Links:
    How to post code problems
    How to Post Performance Problems
    Create a Tally Function (fnTally)
    Forum FAQ

Viewing 11 posts - 1 through 11 (of 11 total)

You must be logged in to reply to this topic. Login to reply