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

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.
Reply


Messages In This Thread
RE: Comments and explanations - how to do it better? - by Narf - 01-09-2016, 05:19 PM



Theme © iAndrew 2016 - Forum software by © MyBB