CodeIgniter Forums
Comments and explanations - how to do it better? - Printable Version

+- CodeIgniter Forums (https://forum.codeigniter.com)
+-- Forum: General (https://forum.codeigniter.com/forumdisplay.php?fid=1)
+--- Forum: Lounge (https://forum.codeigniter.com/forumdisplay.php?fid=3)
+--- Thread: Comments and explanations - how to do it better? (/showthread.php?tid=64066)

Pages: 1 2


Comments and explanations - how to do it better? - PaulD - 01-09-2016

Hi,

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,

Paul.


RE: Comments and explanations - how to do it better? - InsiteFX - 01-09-2016

Hi PaulD,

I try to write my code so that it is self readable, use descriptive names, methods etc;

If you can not read the code then comment it well and then take another look at it.


RE: Comments and explanations - how to do it better? - PaulD - 01-09-2016

(01-09-2016, 03:48 PM)InsiteFX Wrote: Hi PaulD,

I try to write my code so that it is self readable, use descriptive names, methods etc;

If you can not read the code then comment it well and then take another look at it.

I agree, but I suppose my question is, is what does it mean to 'comment well'? What rules do other people use during commenting, and when do you add the comments, given that it is really hard to tell when you are coding what is obvious and what is not to your future self.

I feel that I need a new phase in my process that is all about commenting code, when the site goes live, when it is still fresh, and not just during the coding process. A new phase that is about 'commenting well' the code that is now finished and tested and ready for production. I have never done that before, just relied on commenting as I go. So what do you do? Yes, code is usually self readable and uses descriptive methods and functions, but do you have a commenting phase? Do you go through your code to comment especially for future development. I suppose this is getting towards documentation, which in all honesty I never write. Perhaps I should?

Paul.

PS Although I have built complex sites, and am quite proud of some of the stuff I have done, I am still fairly amateur in that I have never coded in a team. I am guessing that in a team, commenting becomes a more rigid process, explaining the logic of code protions. But that is outside my experience so I just don't know.


RE: Comments and explanations - how to do it better? - cartalot - 01-09-2016

one thing that has been helping me is to make some of the comments in the form of questions, especially for things wrapped in an if check. that way its not necessary to read the code inside the if to get the general sense of what the method is doing or checking for.

like
Code:
// did the contact form validate?
implied: if it didn't we are going to show the contact form again

Code:
// is there inventory for the product?
implied: if there is no inventory we can't buy this item

Code:
// did the transaction complete?
implied: if it didn't then don't complete the order


RE: Comments and explanations - how to do it better? - Narf - 01-09-2016

First of all, you should avoid commenting too much. If it doesn't take you more than a few seconds to understand what a line of code does - it doesn't need to be explained. CI's config files are heavily commented because they need to explain to thousands of users (who are often complete newbies) what each setting does, but if you look at the actual framework code, there are few inline comments.

As far as how to comment goes ... you need to use your common sense, but here are a few tips:

- Is it obvious what the code does?
- Is it obvious why the code does something?
- Is there a reason the code is written in a specific way? Was it changed recently for some reason? Would somebody else write it differently if they didn't know about some detail?

If the answer to any of these questions is "Yes", then you need to explain that in a comment.


RE: Comments and explanations - how to do it better? - InsiteFX - 01-09-2016

Well said @Narf,

Another thing I would like to add to this is that I also use TODO's in comments if I feel that I may need to rewrite the code later.
( one of the thing's I love about PhpStorm ).

I was taught to get it to work first then add all the bell's and whistle's later and tweak the code.


RE: Comments and explanations - how to do it better? - Diederik - 01-09-2016

@InsiteFX, I also like the todo features of PhpStorm. For those who don't know, it has nice comment highlighting and you have an overview of all todo's in your entire project.

I try to write very short oneliners for comments as I code along. At the end of the day if I have a few minutes to spare I spend reviewing the code I did that day and add some more comments if needed (or add a todo comment if I believe some refactoring could be usefull for example). But truthfully it's hard to follow this...

If I move some code from a controller to lets say some trigger event inside a model I always leave a small comment referencing this change at the original place. It can help you save some time later on figuring this out if you forgot you refactered this peace of code.

Another thing I would recommend is to review your own code periodically.


RE: Comments and explanations - how to do it better? - InsiteFX - 01-10-2016

I also like to put a comment in my code where a method is calling another method to point to the file that it is in.

A year from now it will really help instead of trying to search around for it.

IE: ( This method calls this method in this file ).

TODO: Refactor this code for more speed later on.


RE: Comments and explanations - how to do it better? - includebeer - 01-13-2016

For large or complex projects it's a good idea to write a specification document detailing the business logic and the database structure. In the code, I try to write comments in a way that any other developer could understand what the code is doing and work on the project. If a function do something special I will explain why it's doing it. Because in 6 months I won't remember. For example, if a function read a CSV file, I will explain the format expected.

Maintaining your comments may be a nightmare if you make a lot of changes in your code but I think it's worth it. If you say you will do it at the end of the project, you will not! You won't have the time or the motivation to do it!


RE: Comments and explanations - how to do it better? - PaulD - 01-14-2016

@includebeer
Yes I agree, it is either as I go along or not at all.

In a new project I am starting today I am trying really hard to comment as I go, with a view to my future self re-working the code for whatever reason.

I had some reworking to do earlier today of an older site and quite honestly it was driving me up the wall. A few explanatory comments would have helped a lot. It is not a problem in simple sites, my comments are sufficient and minimal. It is when you have a controller that is actually doing tons of complex jobs, in the middle of a complex app that has multiple user types, multiple permissions, multiple status settings and conditionals etc etc.

So in conclusion I am now trying out a rule of 'if it is a complex method that does not lend itself to easy self-explanation, then I add a comment summary at the bottom, as if it was documentation. So far it seems to be working well but I will only be able to tell when I come back to it in six months time. After all, most methods are completely simple and self explanatory, and writing documentation is just simply too much of a massive task to tack on to the end of a project.

Fingers crossed :-)

Paul.