Coffeehouse Thread

35 posts

What makes good code

Back to Forum: Coffeehouse
  • Lloyd_Humph

    Now that I've gotten pretty good at Visual Basic, im starting to wonder how I can improve my technique. I'm really bad at commenting code when I know i should, so Im going to start doing it! However, as you've been programming longer than I, perhaps you could impart some wisdom and handy techniques you learned along the way? Thanks L

    If Blackberrys are addictive cellphones, Channel9 is the ultimate addictive website.
    Last modified
  • Lloyd_Humph

    Damn you Opera spacing!!

    If Blackberrys are addictive cellphones, Channel9 is the ultimate addictive website.
    Last modified
  • Yggdrasil

    Writing good code is only a small part of the whole puzzle. A more important piece is knowing what code to write. Here are a couple of topics - in and around code - that make for good programmers, in my opinion:

    1) Class/method structure. Knowing when to split your methods into smaller ones, where to refactor your classes into more specific subclasses, and so forth. Tools such as VS2005 and Resharper give good refactoring support, but it's up to us to know WHAT to refactor.
    This is a rather nice list of code smells and appropriate refactorings to handle them. It's java based, but the principles should be the same for VB. You can probably google for more on refactoring.

    2) Design patterns. It takes a while to grasp many of them, but when you do, you go "Oh, so this is what everyone's been talking about all this time?". You feel as if you've been talking in grunts and snorts until someone comes and teaches you this much more elegant language to express yourself. This is a good site for design patterns in .NET.

    Have fun.

  • Dr Herbie

    Lloyd_Humph wrote:
    Now that I've gotten pretty good at Visual Basic, im starting to wonder how I can improve my technique. I'm really bad at commenting code when I know i should, so Im going to start doing it! However, as you've been programming longer than I, perhaps you could impart some wisdom and handy techniques you learned along the way? Thanks L


    Read the book "Code Complete" (now 2nd Edition), then read it again, then think about it for a while, then read it once more. Wink

    Code complete sets out to answer questions like yours; all the stuff they don't normally teach in software books, like how to write good comments.

    IMHO, good code is elegant, and elegance comes by simplicity.  Good code is effortless to read and understand, even when it's doing something complex.  It kind of hard to explain, but you know it when you see it.


    One thing a lot of developers miss out is maintainability; will you (or some other programmer) understand this code in six years time?

    I have found that many solo programmers don't worry about maintainablilty, claiming that they wrote the code, so they'll understand it when they come back to it.  But they don't.  They have to take time to figure it all out again before they can make changes.

    Anyway, like I said, read Code Complete for advise on this type of topic. It's well worth the price.

    Herbie

  • Bas

    I second the motion for reading Code Complete. Make sure you get the second edition, it delves into a lot of OO subjects where the first edition is really starting to show its age. The first five chapters were a bit of a struggle to get through, but after that it's solid gold.

    As for commenting, it mentions an important rule: make the code document itself, rather than rely on excessive commenting. If you have a function called DeleteFile that takes an argument called 'path', it's pretty obvious what that function does: it deletes the file at the provided path. It doesn't necessarily need a lot of comments explaining what it does.

    Also, say you have this function (and I recommend giving your functions better names than 'dostuff'):

    ---

    Private Function DoStuff() as integer

       [bunch of code]

          ' Get the name of the leaf
          if node <> null then 
             while node.next <> null do
                node = node.next
                leafName = node.name
             end while
          else
                leafName = ""
          end if

       [bunch of code]

    End Function

    ---

    (Hmm. How -do- you post code snippets in this editor? Also: example lovingly ripped from Code Complete)

    Now, those lines of code in the middle aren't immediately understandable. You may figure out what they do, but it's quicker if you read the comment above it: it gets the name of the leaf.

    Now, watch what happens if you put those lines of code in a separate function:

    ---

    Private Function DoStuff() as integer

       [bunch of code]

          leafName = getLeafName(node)

       [bunch of code]

    End Function

    Private Function getLeafName(node as byref Node) as string

          if node <> null then 
             while node.next <> null do
                node = node.next
                leafName = node.name
             end while
          else
                leafName = ""
          end if

          return leafName
    End Function

    ---

    What happens here is that the code documents itself: you don't need a comment to explain that you are getting the leaf name in the middle of DoStuff(). That's made evident by the function call to GetLeafName().

    If you can look at code and instantly know what it does, that's nearly always better than looking at a comment and instantly knowing what the code below it does.

    But again, if you have the money, getting Code Complete 2nd Edition is a good idea. It will also last you longer than many other programming books, which may be outdated next year.

  • Chadk

    I seco... third reading code complete. Its my bible.

    Good code for me is consistency. Both the actual code, and the way the API is build.

  • Bas

    Chadk wrote:
    Good code for me is consistency. Both the actual code, and the way the API is build.


    True. Which is one of the reasons I just can't get comfortable using PHP. Or CSS, for that matter.

  • Massif

    The very fact you're asking the question is a good step towards writing good code.

    For me though, the key to writing good code is to start from a good design. Sadly I can't think of a good design book to point you at.

  • Dr Herbie

    Massif wrote:

    For me though, the key to writing good code is to start from a good design. Sadly I can't think of a good design book to point you at.


    So write one.  Then come back here and point us at it.

    Herbie

  • RamblingGeek​UK

    I'm so glad that tou asked this question. I've been dabbling with Visual Basic 4.0 - 6.0 for years and .NET which I think is awesome.

    I'm always thinking to myself that I could be witting better code.

    Even thinking there muse be better ways, more performent for example of writting your code.

    I should of asked this question here long ago. I do get people asking me to write software for them and I tend to shy away because I don't think my standard is that high, also what do you charge.....

    Great post, this is what c9 is about. Big Smile

  • ScanIAm

    Dr Herbie wrote:
    
    Massif wrote:
    For me though, the key to writing good code is to start from a good design. Sadly I can't think of a good design book to point you at.


    So write one.  Then come back here and point us at it.

    Herbie


    Sounds easy, but it aren't.

    It's like the old quote about pronography:  

       I can't define it, but I know it when I see it.

    It's even easier to find bad design Smiley

  • Dr Herbie

    ScanIAm wrote:
    
    Dr Herbie wrote: 
    Massif wrote:
    For me though, the key to writing good code is to start from a good design. Sadly I can't think of a good design book to point you at.


    So write one.  Then come back here and point us at it.

    Herbie


    Sounds easy, but it aren't.



    Is too.  Just needs, you know, diagrams with arrow an' stuff.

    Herbie

  • JohnAskew

    One word:   reuseability.

  • Ion Todirel

    JohnAskew wrote:
    One word:   reuseability.
    actually many words, like: comments, modularity, maintability,  consistency etc.

  • anand.t
  • ScanIAm

    About the only clever technique I wish I could impart to any and all coders:

       Fight the urge to be clever

    I've seen too much code that is clever and unclear.  Machines will always get faster, more memory, etc, so there is no more reason to shave a few bytes by using some indirect, obscure method.

  • harumscarum

    following your companies standards

    Simple, knowing you can always go back and refactor.


  • Lloyd_Humph

    Ill definately be getting that Code Complete book then Smiley Looks good - is each chapter self contained? AS in, could i jump to the bits i wish to look at first? I normally just read the whole thing - even the stuff i already know - in a hope to learn sometyhing new - but with a 1000 page (ish) book ill be reading it for a long time Expressionless

    Thanks for all the posts, keep em coming. Anyone suggest a good Design Patterns book - roughly £20?

    Thanks

    Lloyd

    PS: Glad you're enjoying the thread Smiley

    If Blackberrys are addictive cellphones, Channel9 is the ultimate addictive website.
    Last modified

Comments closed

Comments have been closed since this content was published more than 30 days ago, but if you'd like to continue the conversation, please create a new thread in our Forums, or Contact Us and let us know.