Welcome Guest, Not a member yet? Register   Sign In
Comments and explanations - how to do it better?

(This post was last modified: 01-09-2016, 03:17 PM by PaulD. Edit Reason: simple typo )


I often find that when I return to code, even within the same application I am writing, I have one of three thoughts.

1. 'wow, I did that well' or 'I can't believe how clever that was' or 'I am good' :-)
2. 'Why on earth did I do it that way'
3. 'What on earth is going on here?' or just simply 'eh?'

In order to get more 1's than 2's or 3's (above) I have been experimenting with comments. Now my usual rule is to only comment when it clarifies the code, but that is very subjective. What seems obvious when coding with everything fresh in the mind can be a maze 6 months later.

So in a project I did a while ago I went with the rule of 'comment everything' inspired by CI config files (which have lots of comments that I really appreciate when a questions arises). But when I came to making alterations to that code some of the comments were as mysterious as the code itself.

Here are some examples of genuine comments I found in my code (which I share in shame because even to me they mean nothing):
PHP Code:
// update pe_ref lines that need art 89 to ordered 90

// check all the order lines (not just the ones needing art) to see if any on this price reference now need 56

// put line ids into unique reference array if not current line or art needed or price reference is null 

I also tried doing the commenting at the top to explain the logic in whichever method, but found keeping them up to date was a nightmare, tedious and essentially mostly a waste of time, especially during development.

I now think that what I need to do, is when a site first goes live, and I am (mostly) on top of what the code is actually doing, that I should introduce a new stage to my process called something like 'make the code intelligible'. An entirely new process of going through every file and commenting, explaining and annotating. I have always felt I do this as I code anyway, but past experience of editing my own code has often left me baffled.

What do other people do about this? Especially with complex admin sites or complex user systems where the code does not necessarily lend itself to self explanation?

Any advice, tips or shares of your practices when it comes to this would be warmly welcomed, as I simply do not know how to improve this aspect of my coding, or to avoid those 'what is that all about' moments.

Thanks in advance,

Best wishes,


Messages In This Thread
Comments and explanations - how to do it better? - by PaulD - 01-09-2016, 03:15 PM

Theme © iAndrew 2016 - Forum software by © MyBB