Coffeehouse Thread

19 posts

"We" / "The program" / Other

Back to Forum: Coffeehouse
  • User profile image
    W3bbo

    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) );
               

  • User profile image
    Bas

    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.

  • User profile image
    Sven Groot

    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. Tongue Out

  • User profile image
    PerfectPhase

    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 Smiley

  • User profile image
    MasterPi

    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.

  • User profile image
    ScanIAm

    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.

  • User profile image
    Angus

    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

  • User profile image
    jsampsonPC

    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 Smiley

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

    // I can haz a conekshun?

    // why can have stregn to?

    // Hai! Can setz conektshun streng?

    // kthxbai!

  • User profile image
    blowdart

    jsampsonPC wrote:
    I usually use plural-refernces too.



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

  • User profile image
    jsampsonPC

    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? Smiley

  • User profile image
    ScanIAm

    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 Smiley

  • User profile image
    blowdart

    jsampsonPC wrote:
    

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


    Ummm Perplexed

    Well yea, but what would comments like that be adding? All you're doing is rephrasing what each line of code does.

  • User profile image
    MasterPi

    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
    */

  • User profile image
    W3bbo

    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

  • User profile image
    irascian

    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)

  • User profile image
    Mary_Jo_​Foley

     // 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) );

  • User profile image
    blowdart

    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 Big Smile

  • User profile image
    ScanIAm

    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.

Comments closed

Comments have been closed since this content was published more than 30 days ago, but if you'd like to continue the conversation, please create a new thread in our Forums, or Contact Us and let us know.