To comment or not to comment? (not even a question...)

Not for 'how-to' coding questions but PHP theory instead, this forum is here for those of us who wish to learn about design aspects of programming with PHP.

Moderator: General Moderators

User avatar
Oren
DevNet Resident
Posts: 1640
Joined: Fri Apr 07, 2006 5:13 am
Location: Israel

To comment or not to comment? (not even a question...)

Post by Oren »

Of course "to comment", but yet, here is a topic which I've just read on SitePoint: http://www.sitepoint.com/forums/showthread.php?t=468872
Thoughts, comments, anything?

P.S Read it till the end before posting here :wink:

Edit: The link I've posted was pointing to the second page of the topic - by mistake. I fixed that and now it points to the first page :wink:
Last edited by Oren on Mon Apr 02, 2007 4:16 am, edited 1 time in total.
User avatar
John Cartwright
Site Admin
Posts: 11470
Joined: Tue Dec 23, 2003 2:10 am
Location: Toronto
Contact:

Post by John Cartwright »

I think this comment pretty much sums my exact sentiments.
Adam A Flynn wrote:On the subject of comments, I would always opt for better comments over system performance. There is certainly a point where comments can just be cumbersome (and I think that point depends on the individual developer), but, we're talking about a few milliseconds in the difference here. Buying a stick of RAM for $100 is way cheaper than me wasting a few hours trying to figure my way through poorly documented code at $50/hr.
Xoligy
Forum Commoner
Posts: 53
Joined: Sun Mar 04, 2007 5:35 am

Post by Xoligy »

Oh gee, this brings back memories of a "debate" on another site where someone claim that do:

Code: Select all

if ($bob){
// bob
}
else {
// no bob
}
Was more efficient than

Code: Select all

if (!$bob){
// no bob
}
else {
// bob
}
and even if it went against logical thinking you shouldn't use the '!'.

For it to have any effect at all, you'd have to have millions of people accessing the same file at the site time, and even then we're talking a second at the most.
User avatar
dreamscape
Forum Commoner
Posts: 87
Joined: Wed Jun 08, 2005 10:06 am
Contact:

Post by dreamscape »

Xoligy wrote:and even if it went against logical thinking you shouldn't use the '!'.
I actually try to avoid using ! by itself if possible, not for performance, but because it makes the code more readable if you do a direct comparison (and if you can do "===" or "!==" then bonus points for more readable code that *improves* performance). A lone ! can easily get lost in the mix when you are scanning code.

Code: Select all

if ($bob !== false)
{
    // bob
}
else
{
    // no bob
}
User avatar
Oren
DevNet Resident
Posts: 1640
Joined: Fri Apr 07, 2006 5:13 am
Location: Israel

Post by Oren »

dreamscape, check your PM box :wink:
User avatar
Christopher
Site Administrator
Posts: 13596
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Post by Christopher »

Good one dreamscape...
(#10850)
User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

Post by Ambush Commander »

I think the whole debate on comments is silly. However...

On the larger subject of compactness versus verbosity, I think it depends on the person actually doing the reading. When code is compact, it's easier for advanced developers to skim over it and get to the meaty sections. For less-experienced developers (not necessarily just in terms of PHP experience: it could also be experience with the application at hand), however, the verbosity helps space out concepts, easing comprehension.

It's sort of like those novels you had to read in English. There were really dense ones (think To The Lighthouse) and the easy reads (think Dracula). Is any style of writing more legitimate than the other? Is any style easier to read?
User avatar
Christopher
Site Administrator
Posts: 13596
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Post by Christopher »

Ambush Commander wrote:I think the whole debate on comments is silly.
One of the reasons it is silly is that comments is only one part of maintainability, but often gets conflated as maintainability. There are a number of issues, which I might break into a few broad categories: code quality, good design, documentation, unit tests. Comments are only a subset of documentation. I think I would prefer good design and code quality (i.e. consistency, quality of naming, algorithm choice, modularity, etc.) to comments if given a choice. I might even say that reasonable external documentation covering architecture, design decisions, etc might be more helpful. And unit tests are both the best kind of documentation and something that provides confidence when making changes.
(#10850)
User avatar
Maugrim_The_Reaper
DevNet Master
Posts: 2704
Joined: Tue Nov 02, 2004 5:43 am
Location: Ireland

Post by Maugrim_The_Reaper »

It's interesting to hear peoples view of comments. I've known people who veer from verbosity to vague one liners and depending on the context both can work. In general though, if you take and piece of code it's first line of commenting should be the naming of variables and functions - if variables don't tell you what the represent, and functions not describe themselves, then it's obvious you're going to get lost very quickly. Of course even this can be a failure if you don't split your functions into small discrete ones. Having a 200 line function broken into a set of 4-5 smaller functions (with descriptive name) will obviously aid understanding.

Same advice arborint noted above of course - but it's pretty important to remember it. The more modular, descriptive naming, reference naming, etc. you build into your code, the more easily a developer can read it, and understand it. I also find the use of Interfaces and Abstracts to be useful since after reading those, concrete subclasses become obvious.

As for comments themselves - depending on the context of the code, I either stay with phpDoc comments or move into far more verbose territory. For example, it's very hard to avoid commenting when coding to a specification since you need to keep a running of reference to what parts of the specification are implemented where - this is one example area where unit testing as documentation can easily fail. Consider a specification driven format like JSON or YAML - the public interface will be a simple encode/decode pairing so while the unit tests will ensure the appropriate specification is adhered to, there can conceivably be thousands of lines of code sitting behind the tests you'll have to understand before you can make changes.

I see few disadvantages, in all honesty, with verbose comments. At least it's better than too few ;). A long properly formatted comment can easily be skipped across. IMO though, the most natural comments are written as you develop, when your thoughts are focused, your unit tests passing and you're less inclined to wordiness or to commenting everything.
User avatar
Oren
DevNet Resident
Posts: 1640
Joined: Fri Apr 07, 2006 5:13 am
Location: Israel

Post by Oren »

I was more thinking about your thoughts whether it slows the script down or not when you have lots lots of comments.
User avatar
onion2k
Jedi Mod
Posts: 5263
Joined: Tue Dec 21, 2004 5:03 pm
Location: usrlab.com

Post by onion2k »

It slows your script down. So what though? So long as it's fast enough that's all that matters for most websites. People spend far too much time and effort optimising their code unnecessarily. Sure, you might be able spend a couple of hours refactoring or redesigning to shave another 0.02s off the execution time, but that time would definitely be better spent improving the user experience by rewriting your error messages or adding some extra help to the site or tidying up the HTML or something.

If you're worrying about the time comments are adding to the time your script is taking then you're focusing in the wrong place.
User avatar
Maugrim_The_Reaper
DevNet Master
Posts: 2704
Joined: Tue Nov 02, 2004 5:43 am
Location: Ireland

Post by Maugrim_The_Reaper »

Performance impact from comments is a non-issue. There are any number of reasons why, but the easiest way is showing a summary list of how optimisation could be organised.

1. Develop the source code
2. Avoid premature optimisation
3. Attain a milestone, stabilise code (e.g. pass unit tests and requirements)
4. Benchmark the source code, and perform a performance analysis (e.g. XDebug + KCacheGrind/WinCacheGrind)
5. Identify performance sinkholes, bottlenecks (e.g. typically the DB, File I/O, specific areas within the overall design)
6. Concentrate on eliminating/optimising/reducing the performance impact of the major suspects, i.e. focus your efforts on where it will offer the most improvement.
7. Go back to 4. and repeat (a lot of times)
8. Learn a good built tool, like Phing..

Number 8 is really interesting. If comments are a concern for performance only, you could build a production copy from your source code using Phing which has a Phing Task assigned to use a Regex to strip comments from the source files. Faster perhaps is php_strip_whitespace() though this also strips non-required spacing in files (which some on particularly strong medication might also view as optimisation...) So you see, comments in files really are a non-issue. They will not appear in your data analysis on performance, and therefore they do not exist when initially optimising. Later, you can play around with Phing on creating builds with or without comments (which would at least offer you the chance of benchmark comparison to justify their removal if they really are a major worry).

In all honesty, compared to database access and file read/wrotes, I doubt comment stripping would have much impact. If something that small is a worry, use Phing to strip them. See, don't even need a hardware solution for those few milliseconds! ;).
User avatar
Oren
DevNet Resident
Posts: 1640
Joined: Fri Apr 07, 2006 5:13 am
Location: Israel

Post by Oren »

Guys, in case that by "you" you were referring to me, I want to clarify something... I asked for your thoughts and was interested to hear what different people think about it. Never did I say/suggest that I'm worried about it and/or looking for advice. All I wanted was a nice discussion, that's all.
If you didn't mean to me personally by "you" then you can totally ignore this post.

Ok, now you can continue this discussion :P
User avatar
onion2k
Jedi Mod
Posts: 5263
Joined: Tue Dec 21, 2004 5:03 pm
Location: usrlab.com

Post by onion2k »

The biggest problem I can see with this discussion, especially the SitePoint thread, is that a newbie coming to it may think "My script is slow, I'll delete all my comments!". They won't see an improvement and they'll end up with worse code. To suggest removing them is a good idea in any way is pretty bad advice on a public forum.
fastfingertips
Forum Contributor
Posts: 242
Joined: Sun Dec 28, 2003 1:40 am
Contact:

Post by fastfingertips »

In my humble opinion commenting the code is also related on how the code is written.

I'm saying that because i really hate messed code. I remember that once i say a ternary operator abuse on over 4 lines and believe me combine this with some object chaining and the devil code is prepared to mess your brains.

I think that is common sense to follow some coding standards when you are not developing your site (and even then is not an excuse because if you will return on that code after some time it will eat your time to remember). I try, no matter that we don't have a variable type to prefix a variable that will hold an array with an "a", an object with "o" and to choose names that describe the purpose of the variable. For example is a big difference between "$aUserList" and "$u".

If you follow the standards the comment should be applied at the beginning of the page/class/method, add comment to the class properties or variables and also in the areas where are some tricky solutions or high processing etc. In this way you wont loose to much time writing poems but you maintain the comments to a fair level.
Post Reply