Leaving dev comments in code

[mcd]

Often times a developer will leave comments in code that are strictly intended for other members of the team to view and refer to, but they aren't intended for anyone outside of the dev team to see. Sometimes, those comments are a bit "colorful", and can contain an expletive or two.

Personally, I think it's inappropriate to use any sort of foul language in anything done for a client, even if it's for internal eyes only or is removed before the site is launched. There's always a chance the client will see that language, so why take the chance and end up looking foolish.

Thoughts? Are comment tags fair game for developers to speak freely and use any language they wish?

FYI, the reason I brought this up was because I was looking at the source code of a site done by a former employer and saw this in the homepage code (edited by me for forum posting):

<!-- I ended the main container in the header because it was f---ing sh-- up, dont remove this div -->

<!-- This is the news letter div, change the sh-- below 4 updates -->

[Mittineague]

Comments like that aren't Professional.

The examples you posted are more venting frustration than providing helpful information. i.e.
What is "sh--"? - a particular element, group of elements ...
How is it "f--" things up? rendering, breaking javascript ...

I guess it depends on whether or not you want Pros or hacks working for you.

[oddz]

In my opinion that type of language is not appropriate in publicly accessible code such as; HTML, CSS and JavaScript. However, you can swear all you want in server-side code,lol.

[ChrisWiegman]

As far as I'm concern comments are fine but all comments should use professional language. I don't care who sees the code. Lack of professionalism on the part of someone who sells him or herself as a professional is never appropriate.

[cpvr]

I believe is using comments so that other developers know what each feature does.

Like "This query does", or "this query is for.." If you're having multiple developers, you should make things easier.

[buzzerchat]

i have hired many developers but found out few of them leave comments in the code, those who are very good in writing code leaves comments! Those who are just in hurry doesn't leave comments in code.

[TheRedDevil]

Its important to leave comments when programming, though its a even better idea to program in such a way that your code itself is explanatory enough.

These days I only leave comments in the vardoc description of a method and perhaps a line or two with comments inside the method if needed, other than that descriptive variable names etc explain the code good enough.

If the comments you mentioned, was even required is another question. Code wise they should not be required, as its html code. As Mittineague mentioned, the context of the comments looks more like they guy was venting frustration with the comments. On a side note that does indicate that he/she was working on something that was a little over their head.

It is important to NEVER write anything that could damage yourself, the company you work for, or your client in any part of the code, internal reports etc. As you never know who will end up reading it in the end. Even a comment as "I am so mad about the stupid decision the client did regarding X instead of Y" can possibly end your career if the wrong person read it.

[Mittineague]

I've gotten into the habit of leaving comments as a type of h tag heading in large complex files. It helps when I'm scanning the code to be able to see what code block I'm in without needing to read any code. True, I can figure out where I am by looking at well named function and variable names, but it's a lot easier to see
/* Database Section */
.....
/* File Reading Section */
etc.

[joebert]

It depends on the atmosphere, I like to try and fit in with whatever/whoever I have to work with.

[Jason__C]

First off, the OP's developers comments were hilarious. However, commenting is an art, just like coding, and I think they are equally as important. Not just for personal use, but helps get you into the habit if you decide to go corporate, with proof of you practicing it.

[Stomme poes]

I swear in my comments, usually in LOL/l33t (like "browserX fux0rd w/ pos:rel").

/* m0aR IE retardation! w00t! */ (obvious IE hack is obvious)

/* I \2665 microsoft! */ (more obvious IE hack is obvious)

/* Chrome duz newlinez abso-po'd offscreen labelz */ (why I used display: none to hide a form element instead of the better abso-po negative margin)

/* YAFFB */ (Yet Another FF Bug) or
/* GO! TEAM! MOZILLA! DECADE-OLD (element) BUG REARS ITS UGLY HEAD YEAH!!!! */ (usually after strange-looking -moz hax for garbage like legends)

/* 4 teh JAWZ */ (I did something particularly for JAWS and similar readers)

/* IE6 no deserve! so NO CAN HAZ */ (transparent pngs, javascript, mobile goodness, whatever)

/* Konq == kutbrowser */ (reason for extra otherwise unnecessary line of code)

/* DUZ NOT WERKSES WITH TEH OPERA YO */

/* Hateses teh (browserX), hateses it */ (obvious hack is obvious but needed to be repeated everywhere and doubled the code)

//Ajaxitty ajax is ajaxitty
(means it worked but not how I'd hoped... if it's really bad, I use a competing football club's name for the ID (#feyenoord) instead of #ajax)

These are usually at work where the code is always a work in progress and is not given to any "clients" (we are the client). The above is clearly not useful commenting for anyone but me.

Anything I've done for some actual client (or will be maintained by someone else) only has sensible Dutch comments explaining or with URLs showing sources of hacks or background images:
/*gecko hack; verdubbeld marges :hover + :focus */

/* ie6 */ (usually don't have to say why)

                  -moz-box-shadow: 0 0 2px #000 inset;
                /*-webkit-box-shadow: 0 0 2px #000 inset;  
uit-comment tot Chrome Skia bug fixed... Chrome-Linux en Chrome-Win alleen
http://code.google.com/p/chromium/issues/detail?id=29427 */
                  -o-box-shadow: 0 0 2px #000 inset;
                  box-shadow: 0 0 2px #000 inset;

ie, actually useful comments.

Though once after implementing mod-rewrite, we added a real 404 page, but there was little there but a single line saying "page doesn't exist" (the same menus from all the other pages are on that page), so my colleague and I added a picture of the bunny with a pancake on its head for filler. The bosses found out months later and were perplexed and we had to take it down. =:3

Names and id's may reflect who they were written for:
#iesux
iesux.css
filenameie6.gif
#mozCantDance
.wallStreet (anything marquee or ticker-like)
#tehDennis (an annoying popup ad insisted on by a co-worker) and evilpopupsareevil.js to run it
.nestedCenterTagsRule (code to replace nested center tags... never implemented. <center><center>still on the page</center></center>)

I find it hard to stick to professional at my work, mostly because the way things are run there, nothing makes any sense anyways and morale is kept alive solely through the existence of LOL.

Staying professional for an actual client is easy to do.

[John_Betong]

Reminds me of a post I once saw:

"Always code as if the programmer having to maintain your code were a raving lunatic who knows where you live."

[deathshadow60]

While I am known for some truly colorful speech, I've never been wild about those types of comments in code; Particularly in interpreted programming languages...

... and while HTML/CSS are not truly programming languages... Wait, no!!! It's a series of instructions telling the computer what to do -- After 34 years of ADA to ZZT-Oop I'm pretty sure that's what a program is. File that alongside the idiocy of calling XML a machine parse-able data format.

For all intents and purposes HTML and CSS suffer the problems common to interpreted languages; the biggest of which being the size of the program affects performance, making comments flat out being bloat.

So it comes down to a question I had drilled into my head by a nun with a metal ruler (see also why I'm so strict on my indentation)-- how does this comment help the next person who comes along?

In an interpreted language (as opposed to a compiled language) comments should be terse, clear and free of needless banter.

It's also why I object to COMPLETELY IDIOTIC comments like:

<!-- start content -->
<div id="content">

No ****, REALLY? Opening a DIV with the ID content is the start of the CONTENT?!? I NEVER WOULD HAVE GUESSED.

Then there's how IE and FF can both screw up if comments end up between sibling level elements -- for IE it's for between floats and sometimes between inlines, for FF I've seen it treat comments as block-level depending on what version you're running; and with FF's propensity for code regressions it better to not risk it...

Which is why this type of comment:
</div><!-- end content -->

Is just as silly AND problematic. It being after could put it between sibling tags, and closing a tag means the end of something? Do I have to say it?

... and the 'fix' is so simple, and clear as a bell what's going on...

<!-- #content --></div>

The # tells me I'm talking about an ID just like how you refer to it in CSS, and the tag itself tells me what I'm doing with it.

There's an article on IBM's web developer website I always link to when the subject of comments comes up. It's meant for C programmers but I think coders of all types can come away with something useful.

Six ways to write more comprehensible code

I'm particularly fond of the "Oh, now we're done?" section.

Now, some people will hear "comments are bloat" and automatically start stripping them out just like they do white-space for deployment; It remains my experience that if you have to white-space strip or resort to any extra compression above/beyond what your server should be providing with mod_deflate, that there is something horribly and horrifically wrong with your code in the first place... A few meaningful comments to make it clear what's being closed and point out anything out of the ordinary alongside some sensible formatting to make the structure of the document clear should NOT have a significant impact upon your page's performance...

...and if stripping them out DOES make an impact, you probably are using old/outdated/half-assed coding techniques (hence people still vomiting up tranny or slapping the 5 doctype on tranny) with problems like a code to content ratio in the markup of 10:1 or more. (when 3:1 is a more practical upper limit). Whenever I see someone practicing comment/whitespace stripping it's on pages blowing half a megabyte on delivering 4k of plaintext.

You also have the issue of people using vague/meaningless classnames like "F style2 egbt" -- don't be too smart for yourself; meaningful names on elements "content", "mainMenu", "sideBar" are as much a part of clear legible code as comments. You see nonsense like this:

<!-- start content -->
<div id="c1289v">

... and that's serious "whiskey tango foxtrot" territory. If they just named it content, they wouldn't need the comment. It's also part of why classnames like "clear", "left" or "red" are also a miserable failure as they don't answer the question "why" and defeat the point of using CSS in the first place. You should be saying what the element IS, not how it appears. WHY is it red? Is it a standout? Is it something getting emphasis? WHY is it left? Is it a sidebar? a leading plate? If you're going to use classes that way you might as well go back to HTML 3.2 and use the FONT tag and ALIGN attribute as you've COMPLETELY missed the point!!!

But to put that in perspective I consider the 'nav' class/id name completely vague and meaningless; every link on a page is navigation, that doesn't narrow it down a whole lot... Which is why I consider HTML 5's nav element a waste of code, and why I usually give my menu's meaningful names like "topMenu", "mainMenu", "subMenu", "footerMenu", etc, etc, etc...

Bottom line, comments should be used to make vague sections of code clear -- which means you document things that are out of the ordinary (like IE fixes in the CSS) or closing tags that are far enough away from the open to need it... and extraneous bits of ranting just don't belong in there if they do not add any extra meaning to the next person to come along. As many seasoned programmers will tell you if you feel the need to document every single line of code, you need to go back and learn how to program... as in most cases verbose variable names -- or in the case of HTML verbose class/ID names with semantic markup and proper indentation -- can often preclude the need for extra comments.

We aren't talking about compiled languages here where you can comment until blue in the face and it has zero impact on the binary.

[Stomme poes]

You should be saying what the element IS, not how it appears. WHY is it red? Is it a standout? Is it something getting emphasis? WHY is it left? Is it a sidebar? a leading plate?

Because someone demanded it just because? His wife likes the colour red? It makes him think of Christmas and happy things? He's had 2 cups of coffee today instead of one? <-- real world hits us

Why I have resorted to using names for id's sometimes. Why is this here? So-and-so thinks it "makes the site pop", whatever that means.

[deathshadow60]

Because someone demanded it just because? His wife likes the colour red? It makes him think of Christmas and happy things? He's had 2 cups of coffee today instead of one? <-- real world hits us

Why I have resorted to using names for id's sometimes. Why is this here? So-and-so thinks it "makes the site pop", whatever that means.

That's when you ask them WHY. Explain to them that if they cannot answer with a rational "WHY" then it shouldn't be done...

Though for "pop" that would be what is called a "standout", or perhaps bold/emphasis or some other semantic phrase element.

Although if they still insist upon it, that's the point where I'll often walk away and a hefty part of why I stopped taking on new clients and went to go do something else -- I couldn't put up with the dipshit nimrods wanting to flush their own websites down the toilet anymore.

As I've more than once told clients "If you think you know so damned much about it, what the devil did you hire me for?"

[Stomme poes]

Explain to them that if they cannot answer with a rational "WHY" then it shouldn't be done...

I live in a world where I gotta pay the mortgage. I've explained plenty, the other dev has explained plenty. But we do not make the decisions.

Though for "pop" that would be what is called a "standout", or perhaps bold/emphasis or some other semantic phrase element.

I wish. It's more like Let's make the web site pop more kinda thing.
Bosses are intent on stuffing as many keywords into text as they can (until it's no longer comprehensible by actual humans). There is no idea of "semantic". They want it to pop. And their wives like colour X. And a kitten.

Although if they still insist upon it, that's the point where I'll often walk away and a hefty part of why I stopped taking on new clients and went to go do something else -- I couldn't put up with the dipshit nimrods wanting to flush their own websites down the toilet anymore.

You Are Retired. I'm not. I'm not freelance either, nor am I stupid enough to try that route (I would starve). The best I can do is explain but sometimes the thingie is still red just because. I could rip out my brains trying to invent a semantic name or I could just call the damn thing
.joewantsitred {
color: red;
}
and finish the other crap that piled up in the meantime.

I don't think I'm the only person in the universe who has this same problem. Of course, it will be fully solved once I become Non-Benevolent World Dictator For Life With The Iron Fist. But that's still in the plans.

[JREAM]

HAHA Those comments are hilarious but I would prefer the person doesn't do that.

[mcd]

The really amazing thing about the comments I referred to above is that they were in a homepage that was really pretty basic. Nothing fancy, under 100 lines of HTML, no CMS, just simple markup and CSS. Not sure what was so difficult about the divs that the person who made the page felt the need to swear in the comments.

I fired off a quick email to the company to let them know about the questionable comments that reside within their homepage. I was professional about it, although I have to admit I was tempted to mention something about how if they needed a new developer or were looking for someone to build a CMS into their site, they could always give me a call. I could offer a "no f-bombs in comments" guarantee.

[Stomme poes]

I could offer a "no f-bombs in comments" guarantee.

Lawlz, I can see that as a bullet-point in a list of features you offer.

I will comment even simple pages, simply because I support IE6, but it never needs to be anything more than pointing out IE6 code (to whoever doesn't recognise it in the first place). Maybe the comments above are proof of the dev's trouble with simple pages?

[mcd]

...I will comment even simple pages, simply because I support IE6, but it never needs to be anything more than pointing out IE6 code (to whoever doesn't recognise it in the first place). Maybe the comments above are proof of the dev's trouble with simple pages?

I think so. I don't want to link to the site and embarrass the company, but if you saw how simple the site is you'd probably think the same thing.

Ready for the even more amazing thing? As I mentioned in the OP, the site was done by a former employer. That employer is a 30+ person design agency. So it's not a matter of not having the staff or experience to do the job. They came up with a simple design, put some mediocre HTML coder on the project and probably still charged the client $50k (When I worked there a bunch of years ago, the going rate for basic websites was $50-70k). On top of that, the sloppy guy left his colorful comments in the homepage.

For that kind of money you'd think they could at least check the code and clean up the comments.

[Pedro Monteiro]

I have had my share of problems with development teams in the past because of this issue. I have had my clients report me "foul language" in error messages, inside code comments and so on. There is simply no excuse or even a logical reason to do this.

[ScallioXTX]

Off Topic:


The off-topic PHP discussion in this thread is split off to http://www.sitepoint.com/forums/php-...me-740240.html

[Michael Morris]

Back on the topic of cursing.. I sometimes leave mild curses such as "damn" or "bloody" (which I consider a curse even most people don't) in PHP comments. More often I grouse about what the previous programmer did wrong in the comments. As comments go I can be a Chatty Kathy as it where.

This said, a word of advice from the esteemed Mark Twain:

"Profanity, while lacking a certain eloquence, is unequaled in its ability to convey pain. If you don't believe this strike your hand with a hammer."

So there is a time and place for it. Every other word whether written or spoken has no proper time or place except among the uneducated and the crude.

In comment texts if I type a curse and let it stand its because that section of the code was frustrating me and especially difficult to write in the first place. The curse therefore stands as a warning to the next guy that tampering with the code may cause them similar problems.

[deathshadow60]

This said, a word of advice from the esteemed Mark Twain:

"Profanity, while lacking a certain eloquence, is unequaled in its ability to convey pain. If you don't believe this strike your hand with a hammer."

That goes hand in hand with George:

When asked by his nephew about his profanity, Patton remarked, "When I want my men to remember something important, to really make it stick, I give it to them double dirty. It may not sound nice to some bunch of little old ladies at an afternoon tea party, but it helps my soldiers to remember. You can't run an army without profanity; and it has to be eloquent profanity. An army without profanity couldn't fight it's way out of a piss-soaked paper bag."

"As for the types of comments I make", he continued with a wry smile, "Sometimes I just, By God, get carried away with my own eloquence."

... and it often seems to me that today we have WAY too many little old ladies thinking we're dealing with afternoon tea parties and not business. Even funnier when it comes from your metro-sexual dirty hippies who need to go back to singing Lesbian Seagull around the drum circle who get their panties in a twist over daring to say something negative about... ANYTHING.

But as I learned at an early age, "if you can't say anything nice" is a cop-out by limp wristed "me too" wussies who want to stamp out anything resembling progress or improvement... Basically the types who are doomed to be employees their entire lives. Ding, fries ready. Back-slapping hug fests with rose coloured glasses do NOT do anything but harm -- anyone who tells you otherwise is selling something.

Or as George said, "If everyone is thinking the same, somebody isn't thinking."

[willsmith727]

Commenting code is very useful, but commenting code with foul language isn't. Its not professional either and if I did that when I worked at an agency I'd expect to get a ticking off about it. You never know who will see it - the client, visitors to the site etc.