What does style look like, part 4

re: What does style look like, part 4

Mike Weller — Fri, 12 Nov 2004 20:02:00 GMT

Wow, I'm loving that 1980s style!

And with regards to formatting, the one thing I love about VS 2005 is the auto formatting, and customisation of this formatting. Whenever I press return at the end of a line, it is formatted just how I like, and the same when I close a curly brace. Fantastic.

re: What does style look like, part 4

Jeff Parker — Fri, 12 Nov 2004 20:45:00 GMT

Heh, 80's style, Larry where did you first see that style of commenting at to where you picked it up? I know I used it and picked it up somewhere off of a Microsoft Piece of code or example somewhere, liked the style and used it when going to college in the late 80's.

Also one thing kind of left out is the XML commenting style for C# While similar to C there is XML in there in specific orders to help build code documentation

re: What does style look like, part 4

Larry Osterman — Fri, 12 Nov 2004 20:50:00 GMT

TOPS-20 Emacs (the original Emacs, predating Gnu/Emacs) had a Pascal mode that allowed you to write:
(** *)
(** Stuff *)

and then run an emacs macro that would expand it to the appropriate range. I fell in love with it (thinking it was "cool") and used it everywhere I could.

You're right about XML comments, but they're language specific (and this discussion is intended to be language agnostic, even though I'm framing it in C code).

re: What does style look like, part 4

Leonardo Herrera — Fri, 12 Nov 2004 20:51:00 GMT

That 80's style brings me warm memories about direct video memory access libraries :-)

re: What does style look like, part 4

Ilya Birman — Fri, 12 Nov 2004 20:59:00 GMT

I, personally, have a strict rules for C/C++:

1. only // is for comments
2. // is only for comments
3. only /**/ is for disabling code
4. /**/ is only for disabling code

That is very handy: finally, do you ever write a really multiline comment? Never. So // is OK. But when you have do disable some, say, ifthenelse piece (especially while debugging), it's very convenient to use /**/

And, also for debuggin I like using things like this:

//*
code (code, "code");
//*/

(In case someone doesn't know, this kind of comment you can turn on/off by just removing/adding the initial /)

In PHP, there's also are # comments, and my PHP editor, EditPlus, has a fantastic feature to syntax-highlight different comments differently. What I do is I make //'s grey and #'s bright red. So #'s are for important comments, like

# CHECK IF $_POST'ED DATA IS OK!
$a = @$_POST['something'];

Sorry for being too verbose :)

re: What does style look like, part 4

Larry Osterman — Fri, 12 Nov 2004 21:28:00 GMT

Actually, Illya, I often write multiline comments, especially if something tricky's going on.

re: What does style look like, part 4

Jeff Parker — Fri, 12 Nov 2004 21:31:00 GMT

<quote>finally, do you ever write a really multiline comment</quote>

Every day on every method. I do at least. Been caught before by the Go back and add this to your code you wrote 6 years ago. And I sit there look at the code and say What the heck was I thinking there. Then change it and break 50 other things I also coded 6 years ago.Then say Ohhhh thats why I did that. Get caught by that a few times you will write more comments.

More and more I even include snippets of code on how to use methods and classes right in the code as well.

re: What does style look like, part 4

Ilya Birman — Fri, 12 Nov 2004 22:20:00 GMT

Code is actually an implementation of some of your ideas. When you see the idea clearly, your comments are usually guiding you through the implementation, like
"Check if file is accessible" or "Add fulltext index to column C".

If you have written the code 6 years ago, it's very likely that you don't remember the idea, sure. But I do not think that comments is a great place to express your ideas. Comments are needed to describe the actual steps you make.

When I have some "tricky" algorythm, I just go to my Wiki site or even open MSWord and describe it there and save within a project website/folder.

Well, that's how things work for me. Maybe it's because my longest code is 200 KB? :-)

re: What does style look like, part 4

Serge Wautier — Sat, 13 Nov 2004 00:09:00 GMT

In VS, I use a non-default background color for comments (gray. forecolor= black).
It does a really good job at improving readability.
e.g. when you're scrolling down the code looking for a specific piece, it's really easy to read the comments without paying attention to the code. It's just not in your way !

Also, it's really easy to see the beginning of code pieces thanks to 'the gray line above them'.

My 2 cents,

re: What does style look like, part 4

Jeff Parker — Sat, 13 Nov 2004 03:52:00 GMT

Ahhh, Ok, sorry I mistook your you statement about one line comments thinking that was all the documentation you do. My appologies, yes I used to do this as well. But as I commented earlier I use C# commenting and I guess I have been using it for a couple years now. Which allows for a lot of documentation like the word stuff your doing to be written right in your code. C# and .net has really changed my entire outlook and styles of writing code.

And Sorry Larry not meaning to turn this thread into language specific but the C# rules are something I feel so strongly about I can not resist. Like you said before, your boss says your forthright, I said sometimes I am strongly opinionated.

So by following the C# documentation guidelines I do not need to open word, I do not need write additional documentation. I also when going back in time as I have had to go back and modify code written in early .net I do not have to search for documents, I have access to the code and can see all the documentation in one nice file. And I can change the documentation as I change the code.

Now the kicker, with tools like NDoc I can produce full chm files ready to read in a very organized and readable format. I do not produce these chm files for myself, but for others. I personally read the the documentation in my code. Now who others? well this I actually amazed myself. Many people have heard of Sarbanes oxley. Well aparently I impressed someone somewhere to write an article on my code documentation and Sarbanes compliance with it. With the C# XML style and using it exactly how Microsoft recomends I have blown auditors minds when they come in to look at it they are used to seeing reams of paper, books diagrams and so on. And the best thing is, I never used anything other than Visual studio and NDoc to pass all my code through several audits.

Link to an article I was interviewed on about longhorn but turned more into a .net article for me
http://www.adtmag.com/article.asp?id=10162

See the following link for specifics on the C# commenting.
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csref/html/vcoriXMLDocumentation.asp?frame=true

Again sorry Larry not trying to jump your post but the XML commenting I really truely believe is a revolutionary idea and process and style in code commenting. For me at least this is one thing that has permanently changed the way I write code. Much the way you look at the 80's style and say I can't believe I did it this way is how I look at all code comments anymore. The XML style has just grabbed me like a monkey grabs a banana.

re: What does style look like, part 4

Myron A. Semack — Sat, 13 Nov 2004 04:52:00 GMT

Larry, are you going to mention tools like Doxygen in this series? I ask because code-documentation systems tend to impose commenting/formatting rules of their own.

re: What does style look like, part 4

Larry Osterman — Sat, 13 Nov 2004 05:08:00 GMT

Myron, in fact, the next post in the series mentions AutoDOC, which I suspect is essentially the same thing.

Jeff, I'm not trying to belittle the C# XML comments - they'are actually pretty amazing (IIRC, Chris Brumme indicated that the public CLR reference manual is actually generated from the CLR sources). It takes Doxygen and AutoDOC and DocJet to a totally different level.

re: What does style look like, part 4

Andreas Häber — Sat, 13 Nov 2004 09:10:00 GMT

How the .NET SDK and other SDK's are created is in fact written about here: http://blogs.msdn.com/loripe (guess that's what 'the public CLR ref. manual' is?).

Cool that they're using reflection for part of the job. It's really a big opportunity to get a lot of boring doc-work done by the computer(which seems to always love doing the boring-work!).

And yeah, it really sucks reading code where every line is documented(guess I've commited that crime myself). It's often easier to just delete those comments and then read the code :)

re: What does style look like, part 4

Norman Diamond — Mon, 15 Nov 2004 02:27:00 GMT

> And there's the C++ style // comment.

I think BS knowingly and wilfully inherited that comment style from BCPL.

Sometime around 1996 or 1997 or so, some novice computer reviewer wrote an article about the Macintosh, saying that it has a Windows 95-like user interface. Of course the Macintosh's user interface was copied, but it was copied from a famous copier company, not copied from that reviewer's familiar copy of a copy of the famous copier company's work.

However, when C copied //, I think it did so because of the influence of C++ rather than the influence of BCPL. If BCPL had been sufficiently influential in commenting style, then C would have had it from C's start. (Hmm, which did B have, I've forgotten.)

11/12/2004 12:59 PM Ilya Birman

> 3. only /**/ is for disabling code
> 4. /**/ is only for disabling code

That must make it pretty tough to disable code that was written by anyone whose style differs from yours, or written before C copied // style comments.

I use #if 0 to disable code. It also requires a single-character change (to #if 1) to temporarily reenable it during debugging. And it nests.

re: What does style look like, part 4

Philip — Mon, 15 Nov 2004 06:06:00 GMT

Ilya, you're technique of using // for comments and /**/ for disabling a code block is a good idea. Note to self: start using this technique.

re: What does style look like, part 4

foxyshadis — Mon, 15 Nov 2004 06:34:00 GMT

I can see one use for the 1980's brand, which still seems to be fairly common today: The tops of files, to hold all the general information, authorship, and 'mission statement'.

re: What does style look like, part 4

Tibor Harsszegi — Mon, 15 Nov 2004 13:27:00 GMT

Hi,

just some comments.
// is a kinda nasty technique. Some GCC ports
(WindRiver's Tornado is one of them) do not
quite like them. And if you willing to
be somewhat portable, shall note that.
Also I doubt that there is worse than manually
"fixing" the beauty of your code.
I have been using "idnt.exe" (it's a free
(even source, guess you Microsoft guys just
loove the idea) C formatter), you can
do almost everything with it. Specifying
block format style, i.e. K&R or other,
linelength, comment style, removal of
TABs, etc.
Forth taking a good look at, really.
Speeds up "manufacturing" comments and prologs
as hell, since you simply do not bother how
disgusting your comment look like, since it'll
be reformatted automatically.
Nice blog, Larry anyhow! Keep up.

re: What does style look like, part 4

Paul Walker — Tue, 16 Nov 2004 12:14:00 GMT

<i>To me, that's a huge improvement. By stretching out the code and adding some comments, it's already starting to look better.</i>

Oh, I would so agree - that's the style I find most readable, and tends to be what my own code is written in. In the unlikely event we ever have to read each other's code, I think it might work quite well. ;-) After some of the stuff I've read recently, it's nice to find other people who appreciate readable code!

As for disabling code - #if 0/#endif all the way. Much easier than comments, both for enabling and disabling, and Vim also highlights an "#if 0" region as a comment so you know it's disabled. (Vim's auto-formatting is also out of this world - nothing else I've tried comes close.)

What does style look like, part 6

Larry Osterman's WebLog — Tue, 16 Nov 2004 21:10:00 GMT

re: What does style look like, part 4

Ilya Birman — Tue, 16 Nov 2004 21:20:00 GMT

Jeff, thanks for your links, exploring them :)

Unfortunately I don't know NOTHING about .net and CLR. I even don't know what CLR stands for :) Gonna start researching it one day...

re: What does style look like, part 4

Larry Osterman — Tue, 16 Nov 2004 21:22:00 GMT

Ilya,
CLR means "Common Language Runtime" - also known as the .Net framework.

What does style look like, part 6

Larry Osterman's WebLog — Wed, 17 Nov 2004 01:27:00 GMT

re: What does style look like, part 4

Ilya Birman — Wed, 17 Nov 2004 22:28:00 GMT

Cool, coupla days ago I though out "Common Libraries Runtime", so I was rather close to the truth :)

Thanks :)

re: What does style look like, part 4

Pieter Breed — Fri, 19 Nov 2004 05:53:00 GMT

Something that has not been mentioned is commenting styles that will work for more than just one language.

Our development team develops (at the moment) in VB6, C (actually Microstation MDL), C++, VB.NET and C#. These languages are similar enough that we decided to create a commenting style that will suit both the developers and the respective IDE's as well as be generally the same acros the different platforms.

What we settled on was using one-line comments (' for VB, // for c/c++/c#) in the following manner:

' comment describing
' only the next line
<Some VB Code Here>

' comment describing a block of code
' ----------------------------------

VB Code line1
VB Code line2
VB Code line3

VB Code line4
' ----------------------------------

You can do the same with //-style comments.

Sorry for being so verbose :)
p!

re: What does style look like, part 4

Ben Cooke — Fri, 26 Nov 2004 04:27:00 GMT

Back in my younger years I would use loads and loads of asterisks in my comments. Not as many as Larry, mind, but still quite a lot:
/**********************
* Something or Other *
**********************/
(although sometimes I'd use slashes on every line. I settled down after a while.)

However, for the past six years or so I've been using text editors with syntax colouring, so my comments don't need to be so huge anymore. I tend to just do this:
// Something or Other
... and my editor makes them green. The wonders of modern technology.

Larry Osterman s WebLog What does style look like part 4 | Wood TV Stand

Larry Osterman s WebLog What does style look like part 4 | Wood TV Stand — Mon, 01 Jun 2009 01:05:19 GMT

PingBack from http://woodtvstand.info/story.php?id=6623

Larry Osterman s WebLog What does style look like part 4 | Portable Greenhouse

Larry Osterman s WebLog What does style look like part 4 | Portable Greenhouse — Mon, 01 Jun 2009 13:05:54 GMT

PingBack from http://portablegreenhousesite.info/story.php?id=5188

Larry Osterman s WebLog What does style look like part 4 | Portable Greenhouse

Larry Osterman s WebLog What does style look like part 4 | Portable Greenhouse — Mon, 01 Jun 2009 14:30:08 GMT

PingBack from http://portablegreenhousesite.info/story.php?id=14811

Larry Osterman s WebLog What does style look like part 4 | Hair Growth Products

Larry Osterman s WebLog What does style look like part 4 | Hair Growth Products — Tue, 09 Jun 2009 11:25:37 GMT

PingBack from http://hairgrowthproducts.info/story.php?id=4369

Larry Osterman s WebLog What does style look like part 4 | Green Tea Fat Burner

Larry Osterman s WebLog What does style look like part 4 | Green Tea Fat Burner — Sat, 13 Jun 2009 04:25:09 GMT

PingBack from http://greenteafatburner.info/story.php?id=4147

Larry Osterman s WebLog What does style look like part 4 | work from home

Larry Osterman s WebLog What does style look like part 4 | work from home — Tue, 16 Jun 2009 15:07:15 GMT

PingBack from http://workfromhomecareer.info/story.php?id=18107

Larry Osterman s WebLog What does style look like part 4 | Outdoor Decor

Larry Osterman s WebLog What does style look like part 4 | Outdoor Decor — Fri, 19 Jun 2009 07:13:26 GMT

PingBack from http://outdoordecoration.info/story.php?id=4511

Larry Osterman s WebLog What does style look like part 4 | bird baths

Larry Osterman s WebLog What does style look like part 4 | bird baths — Fri, 19 Jun 2009 12:46:33 GMT

PingBack from http://cutebirdbaths.info/story.php?id=3670