No comment(s)…?

// Why comment lines in your code are so important, or are they?

I’ve always appreciated clean code and good comments, but I have to admit I can be a messy code commentator.

This post is a promise to myself: I will comment my code in a better way.

What way, though?

Although programming languages can be very different I believe they have one thing in common: if they are not well organised, they are hard to read.
This includes the way developers write and lay out the code and their comments to it.

After reading few articles online (see list at the bottom of this post), I came up with this top 7 checklist, which is basically a list of how to avoid my bad habits at coding and commenting.

In order to achieve the goal to radically improve my coding abilities I’ll try to follow my own advice and I’ll be more than happy to hear your say!

  1. Separate blocks of code with comments
    /* =Structure ------------------- */
    body { padding: 0 2em; }
    /* =Header ------------------- */
    #site-title { width: 40%; margin: 0 0 0 165px; }

  2. Comment while you edit
  3. Delete the commented lines of code (guilty!)
    background: #fff;
    // maring-right: 2em;
    < DELETE ME!
  4. Use TODO while prototyping (and remove it as soon as it’s done!)
    .three-columns {
      // TODO > define the 3 columns style
    }
  5. Make code as self explanatory as possible (that I do, yay!)
  6. Edit your comments if you edit your code
  7. Avoid obvious comments
    .game-results {
      margin: 1.5em; // add margin around box
    < no kidding
    }

List of interesting articles on the matter

Note: will open in a new window

Oh and happy Saint Valentine’s Day to those who celebrate it.

4 thoughts on “No comment(s)…?

  1. Chris

    8. Comment why, not how

    9. On every block – if you can’t think of a useful comment then is the block really needed? (Note: block, not line so /*here there should be one*/ h1 { }). I have my IDE set to shout loudly at me if I’ve missed a comment block, and the fact that there’s even support for this shows I’m not the only person who thinks it’s a good idea

    10. Consider splitting layout and formatting into different files – you can use multiple sheets and they still inherit from each other so why not split layout out into it’s own file? For example you might benefit from having a standard 3 column sheet to reuse separate from individual site styles…

    11. Go read Code Complete – it’s not HTML/CSS focused as it covers best practice for a huge amount of “traditional” coding stuff but I’d be willing to bet that it’d help you to write much cleaner websites

    Reply
  2. ginestra Post author

    Hi Chris,

    Thanks for your contribution!

    I totally agree with points 8 and 9, on point 10 I am not sure how that would work with CSS: inheritance stays and although I sometimes use multiple stylesheets, I don’t share the same file for different sites, I reuse the code of course, but I don’t point to the same file, if that was what you meant.

    I will definitely check out Code Complete, can’t promise I’ll read it all, but it’s always interesting to have sources to refer too.

    Reply
  3. Chris

    OK… I’ll try to explain why you might do my no 10:

    1) Neater Code – An issue is that you’ll tend to end up with a load of markup for layout and then a load of markup for other stuff (colours, fonts etc). If you’re lucky you’ll have kept stuff together with related stuff but most of the time things end up all over the place. Some layout, some colours, some more layout… If you’re disciplined you go back and move things around to be more sensible either as you go or when you’re nearly done. If you separate out all the layout stuff to a separate file this gets easier to maintain, especially for big style sheets i.e. you get neater code.

    2) Better reuse – I’ll take the example of a 3 tier sheet to keep this simple, but it applies equally to any other layout you might think of. If you have a style “ThreeTier.css” you can copy and paste the FILE itself to whatever project you’re working on, without ever opening it. Don’t be tempted to copy and paste the code (aka code inlining if you want to be a geek). The obvious (if slightly contrived) benefit here is that code reuse is easier. The more subtle point though is that if one day you find a better way to do a 3 tier layout, or you find a bug in your code that makes your style not render in say, IE6, you can fix the bug in your master 3 tier template and apply the fix/upgrade on all your sites by simply copying and pasting the FILE without opening and modifying sheets, therefore upgrades are easier to do and much safer as there’s much less you can do to screw it up.

    3) Less duplication – Suppose I have a site where some pages have 2 tier layout and some have 3 tier layout, but the fonts are the same across all pages – if you have a sheet for each containing both style and layout you end up with one sheet with 3 tier layout and font data and also one sheet with a 2 tier layout and THE SAME font data. Now if you want to change the font across the entire site you have to do it in 2 places. Contrast this with having 3 sheets: a 2 tier layout only, a 3 tier layout only, and fonts data. Each page uses the appropriate layout sheet AND the font sheet. Now because font is only defined in one place we never copied and pasted the font data to two files and only have one place to modify if we need to change anything.

    Hopefully this makes more sense than my initial comment?

    And if you read all of Code Complete you’ll probably become awesome at [insert programming language of your choice] overnight too, which is nice if you ever want to do any serious JavaScript or PHP 🙂

    Reply
  4. ginestra Post author

    Yes, I meant the same think. I’m not sure why, but I thought you were saying pointing to the same file from different websites (sharing)… that didn’t make sense and in fact it wasn’t what you were saying, sorry.

    I’m going to do some research on what they say about multiple files on CSS, best practices et all, because I recall few reasons why you shouldn’t split the core, but don’t want to write vague info. I’ll get back to you on this one.

    I normally create satellite files, that I call plugins, especially if the website I’m building has a modular structure. This, from what I understand, is a similar approach to what you are suggesting.

    And now I’m tempted to give Code Complete a go!

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *