What makes good code

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

Damn you Opera spacing!!

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.

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.

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

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.

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.

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.

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.

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

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.

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

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

One word:   reuseability.

http://msdn.microsoft.com/msdnmag/issues/04/07/EndBracket/

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.

following your companies standards

Simple, knowing you can always go back and refactor.

Ill definately be getting that Code Complete book then 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

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