"​We" / "The ​program&quo​t; / Other

When making comments when describing the program's flow, do you say "we" or "the program" or something else?

I realised that putting "we" in my comments is a bit silly considering I'm the only person who'se going to look at the source.

Example (from some disabled code of mine)

        /// <summary>Creates a tab image suitable for displaying on top of a glass-pipe</summary>
        /// <param name="tabColor">The base color of the tab's front</param>
        private static Bitmap MakeGlassPipeTab(Color tabColor) {
            
#region GDI+ GraphicsPath method (fails miserably)
            
            // It has come to my attention that GDI+ paths *suck!*...
            // therefore we do some hitech shizzle with bitmap locking and BINARY MATH 'n' Logic! woo!
            
            const Int32 width = 190 + 15;
            
            Bitmap bmp = new Bitmap(width, _height);
            Graphics g = Graphics.FromImage(bmp);
            
            // define a graphics path, we fill the path's body, then stroke it with a pen
            
            GraphicsPath path = new GraphicsPath();
            path.AddLine( new Point(10,50), new Point(10,30) );
           

I enjoy making comments in my personal code in the third person. "// Bas should refactor this when he has the time."

It makes me look like a madman.

I think using "we" in this context is ok, same if you write a paper you also use we even if you're the only one who was involved with the research.

And you can always rewrite so you don't actually need it, e.g. you could turn one of the lines from your sample into: "therefore some hitech shizzle with bitmap locking and BINARY MATH 'n' Logic is used".

Also, if you're using the word "shizzle" in your comments the choice of personal pronouns is the last thing you need to be woried about I think.

I don't normally bother with a pronoun in comments, just write '//define a graphics path, fill the path's body, then stroke it with a pen'

I'd also add something about, or a link to why GDI+ paths suck

Why not just use passive voice and go "high tech shizzle is done"

Then you don't have to worry about "we" or anyone else.

mVPstar wrote:

Why not just use passive voice and go "high tech shizzle is done"

Then you don't have to worry about "we" or anyone else.

Yep, I usually use the passive as well.

On a side note, though, I usually like to hide a profanity or two deep in the code comments.  I figure it might make some future developer chuckle if/when they are ever looking at the source.

I fail to see the point in such colloquialised comments. (I myself fail to use comments [in the limited development I do {currently}], however I would hve thought that comments are used for understanding). How does one expect someone to understand the comments if they contain slang? (One might find that one is [oneself] unable to understand these comments at a later date).

I would like to do some more computer programming (I feel). (The "Algorithms" part of the Decision [or Discrete] Mathematics module [of the Further Mathematics AS-Level] is rather suited [with many polynomial order algorithms] to programatical representation).

Angus Higgins

I usually use plural-refernces too.

// Let's make a sqlconnection, how 'bout it?
SqlConnection myConn = new SqlConnection();

// Okay, and now for a connection string
String connString = WebConfigurationManager.ConnectionStrings["mainConn"].connectionString;

// Okay, how about we set that connection string?
myConn.connectionString = connString

// Dude, let's make a command too!?
SqlCommand myComm = new SqlCommand();

... Blah blah blah

Maybe I'll start documenting my code in "lol"

// I can haz a conekshun?

// why can have stregn to?

// Hai! Can setz conektshun streng?

// kthxbai!

blowdart wrote:



jsampsonPC wrote: I usually use plural-refernces too.

Please tell me those weren't real comments in your code

What if they were? I don't have the freedom to comment my code how I like?

jsampsonPC wrote:



blowdart wrote:  jsampsonPC wrote: I usually use plural-refernces too. Please tell me those weren't real comments in your code

What if they were? I don't have the freedom to comment my code how I like?

Sure, but it seemed like you went a bit overboard.  I usually don't comment at all if it is painfully obvious what is going on.  It's only when I have to be clever and that cleverness might confuse me a few months later that I'll comment.

I figure if you keep the functions small, name them well, and put a little bit of documentation at the top of the function, the body should pretty much explain itself.

There is one exception, though.  If I've ever had to 'figure out' someone elses' code, I'll sometimes comment, line by line, to help discover what they heck they were thinking

jsampsonPC wrote:



blowdart wrote:  jsampsonPC wrote: I usually use plural-refernces too. Please tell me those weren't real comments in your code

What if they were? I don't have the freedom to comment my code how I like?

Couldn't you just write a quick comment before your code that sums up what the following code does?

/*
Instantiates new SQLconnection object and Command object
*/

jsampsonPC wrote:

Maybe I'll start documenting my code in "lol"

// I can haz a conekshun?

// why can have stregn to?

// Hai! Can setz conektshun streng?

// kthxbai!

Lolcode.

EDIT: video of it at TechEd, hmmmm

jsampsonPC wrote:



blowdart wrote:  jsampsonPC wrote: I usually use plural-refernces too. Please tell me those weren't real comments in your code

What if they were? I don't have the freedom to comment my code how I like?

Actually you don't. Or if you did what's to stop you writing War and Peace, or hypothesising on the meaning of life?

Comments should elaborate on the code, explain the things that aren't obvious and document it for those who aren't familiar with it and might find parts hard to follow (like yourself when you suddenly have to revisit it six months later).

Stating the bleeding obvious as you've done in your examples simply slows down understanding and readability. It's as bad (some - including me - would argue worse because it has no value and just slows down code readability) as not putting any comments in at all.

You should also use comments for API descriptions where you can be as verbose as you like with the triple slash syntax for things like summary, remarks, code, and cref since THOSE comments would ideally be used to save you having to write any documentation after your code is written (by running Sandcastle against the source)

 // The great and all powerful Oz defines a graphics path, fills the path's body, then strokes it with a pen
           
            GraphicsPath path = new GraphicsPath();
            path.AddLine( new Point(10,50), new Point(10,30) );

blowdart wrote:



Mary_Jo_Foley wrote:  // The great and all powerful Oz defines a graphics path, fills the path's body, then strokes it with a pen                       GraphicsPath path = new GraphicsPath();             path.AddLine( new Point(10,50), new Point(10,30) );

If you were the real Mary Jo you'd just be cutting and pasting someone else's comments and passing it off as insightful analysis

I really hope that isn't the real MJF, because every I see he/she/it post, you guys tear her/him/it a new one...

And that would be mean.