Me and my script

I'm not lonely!

[MatthewHSE]

Working on a few PHP scripts lately, more major than anything I've done previously, I discovered a strange propensity to write comments throughout, describing what's going on, and almost talking to my script like it's sitting right beside me! You know, things like...

// All right, let's start by grabbing the posted data for processing. 
  
// Okay, we've got the data, now let's process it. 
  
// We need to handle this part first or the validation fails. 
  
// If we make it to this point, the data is all okay and we can start adding it to the database. 
  
// Let's throw in a little error-handling, just in case the MySQL server's unavailable...

Does anyone else have this peculiarity, or am I the only one?

[rocknbil]

Too much, I think. My comments are more to explain something that is convoluted or makes little sense, or to remind myself WHY I put it there.

Comments also make good labeling for subroutines, if you're scrolling through a 3500 line script at 3 AM it's nice to have a flag or two to catch your eye.

#####################################
## Read/parse
sub query {

}

#####################################
## sub insert_data {

}

[iamlost]

MatthewHSE: You are definitely in a minority. Unfortunately. Software documentation is an enormous wasteland.

rocknbils minimalist style is adequate for a scripts author. It may not be sufficient for a new hire without recourse to the originator.

I used to do a lot of code "salvage" work most of which involved decyphering, understanding, and documenting what was in use to allow efficient maintenance, changes, etc. I have seen code dumped by the zillion lines and rewritten from scratch because it was thought cheaper or quicker than retro-documention.

Mind you while many programmers talk to their code while coding/debugging/compiling/etc. few write their comments in such a friendly conversationalist style. :-)

My personal method is to extensively comment (a dryer tone than you) the master record of each script/program with the uploaded version similar to rocknbil.

[MatthewHSE]

Okay, so I'm in a minority. Should have known... ;)

Actually, though, my example above was exaggerated to illustrate the point. I don't really write that many comments, though I do say from time to time what "we" need to do next.

I didn't used to comment my code when I started in, but I recently came across some things I'd written many months ago and had a terrible time figuring them out again. Yes, it was bad, awkward code, but I know I'm not over writing bad code yet, so I'm using comments at the moment to help me remember what I've done and hopefully help teach me to write cleaner and more efficient scripts.

So nobody else finds companionship from their scripts? What a shame! ;)

[Debbie_King]

I was always taught that the purpose of commenting code was not only so that you'd remember what you'd done (or why you'd done it) many months later, but in case anyone else had to take over from you (and we all know it's pretty hard continuing on from someone else's code - even WITH comments).

So if I came across some nice 'comforting' comments like yours Matthew, I think that would make the process a lot easier :-)

<added>Mind I must admit I DO talk aloud to myself when coding sometimes</added>

[rocknbil]

I never talk to myself. All the friends in my head are great conversationalists.

[httpwebwitch]

um... no
you're not alone, I do that too.

There have been times when my comments go into ranting mode

function menu(){
// this function sucks, and i know it.
// I know I should be using a recursive
// function here, but I can't be bothered
// to put that much effort into it.
// I know it's never going to go past 4 levels
// deep anyways, so I'm going to nest a
// whole bunch of while loops here
...

[vincevincevince]

I don't tend to comment simple functions much more than a note near the top to say what it does.

However, when I start writing a complex function, I write out a few lines, one for each stage - pseudocode/pseudocomment

Then, I add the code beneath each comment, which neatly leaves comments behind, as well as it being easier to figure out the logic in pseudocode in the first place.

[mincklerstraat]

Funny reading this thread while contemplating rewriting a function for the, oh, probably eigth time.

Yes, I too converse with my scripts; too often, though, I look at what my script is saying (comments I wrote days, weeks or months ago), and think, "what a load of tripe."

I have a tendency to do quick code fixes, commenting out a line, copying it, and changing it, so if it doesn't work I have the 'old' version right there to uncomment. And sometimes I copy huge blocks of code to turn them into functions, and comment these out. Or sometimes I'll change the name of a function, so it's still available if I need it, just never used. This results in some files which are more than 50% commented-out and deprecated code. It becomes even a bigger pain when you want to comment out bigger blocks of code, of which portions are already commented out, so the ending */ ends your comment.

This tendency has gotten so bad with me I built into this code-viewer thingie I have the possibility of BBcode comment highlighting, just so when I have an important comment I don't miss it amongst the sea of jibberish.

[maxi million]

OK...let me say here MatthewHSE has given me wonderful ideas...i always comment my code to understand what it basically does when im reviewing it after a spell of time but never comment it in a way so as to feel im talking to my code.
i think ill start doing that...if my code isnt working may be ill be able talk/beg/cajole it to give some pretty result

//now baby dont gimme a fatal error!

[markbaa]

I sometimes write apologies when I do something that I know is a nasty hack in case someone other than me ever has to maintain it.