Code Delimitation

[~]

How effective do you think that is a code delimitation by means of using code comments that meet these criteria:

- They start with "INIT: [explanation]" above and "END: [explanation]"
- The comments are repeated at least 3 times to make them more visible

Example:

Code: Select all

///INIT: This is a main loop
///INIT: This is a main loop
///INIT: This is a main loop
  while(1)
  {
   ///INIT: Calculate value 1
   ///INIT: Calculate value 1
   ///INIT: Calculate value 1

   ///END:  Calculate value 1
   ///END:  Calculate value 1
   ///END:  Calculate value 1


   ///INIT: Calculate value 2 and 3
   ///INIT: Calculate value 2 and 3
   ///INIT: Calculate value 2 and 3

   ///END:  Calculate value 2 and 3
   ///END:  Calculate value 2 and 3
   ///END:  Calculate value 2 and 3
  }
///END:  This is a main loop
///END:  This is a main loop
///END:  This is a main loop

[AJ]

With proper indentation and/or a syntax highlighter, surely it's already fairly easy to follow the flow of the code?

[ehird]

... yes ... this is highly redundant

Code: Select all

// main loop
while(1) {
	// calculate value 1
	<code>

	// calculate values 2 and 3
	<code>
	<code>
} 

Just as readable to anyone who can program, and less damn bloat. Indentation and brace styles exist for a reason.

[~]

What about a huge source file with hundreds of such pieces? I guess that in such case it would clarify the code, to know where something starts and something ends, and how logic is embedded into other logical constructs.

[ehird]

If your source file has long, winding constructs with lots of logic that cannot be told from later logic, you have problems beyond comment delimitation.

[~]

That looks like a far too simplistic point of view. If the source code is already too complex, there aren't many more things to do to make it more readable if it's already indented.

This is just the beginning, glad to listen useful comments, to find methods to make external code (Linux, etc.) more readable...

[Combuster]

The most meaningful comments are those that describe things that aren't obvious given the code. Hence, stating that you are looping is hardly any use if you put it next to a for() or while(), nor is making comments bigger in size.

If the code has become too difficult to comprehend anyway, then it would be time to refactor it.

[~]

Don't you think it could prove useful when coding something like routines to plot Bézier curves? Maybe that would make more readable code?

What other approaches could be taken? Would "square" chunks of comments explaining step by step suffice?

[Solar]

Code already explain the "how" with utmost precision.

A comment should explain the "why", i.e. what is the ulterior motive of the code. That is why you don't need a comment for each statement, just for each operation.

For the "what", you should have documentation...

[mystran]

This is just the beginning, glad to listen useful comments, to find methods to make external code (Linux, etc.) more readable...

You're not supposed to read such code in Notepad. You can, but it's waste of time, at least unless you know the code relatively well.

First, you want end editor that can do syntax highlighting. It's also helpful your editor can do stuff like show matching parens or jump to them (typically works for those braces as well), and automatically indent code (as in, select a block of code and tell it to indent it properly). Some also like the ability to fold certain parts, though I've found it more useful for editing textual documents than code.

I also couldn't live very long without having incremental search: when you edit the search query, it'll keep finding the first place that still matches. Typically you can hit esc to get back where you started, or enter to actually stay at the match. Ofcourse you often then tell it to find the next match, and such. Once you get used to this, you start using it for general movement within a file just as much as actually finding stuff.

After your code looks pretty, and is colored in a way that allows you to immediately see what is a comment, what is a constant, and what is a keyword, and how parens match, and you can quickly move around within a single file, the next thing is to figure out how to make sense of project with huge source trees with hundreds of files.

And the solution to that is grep. Yes. When you need to find a certain function, you'll just grep for it's name, in all files, recursively for the whole source tree, until you see a line that looks like a prototype. Then you open that file, and search for the prototype within that file. If the coding standard is half-way sane, it's possible to identify prototypes from a single line. Ofcourse you can search for other stuff as well, like defines or whatever, and grep gives you full regex if you need them.

If you can issue the grep-commands from within your editor easily, this can be a really fast way to move around. I usually don't do this, but simply keep a shell and the editor next to each other, using the editor to browse files, and the shell to find the correct file. Ofcourse it helps if your editor can do tab-completion or some similar stuff on filenames, so you can easily open files with complex paths.

....

The short version: grep && (vim || emacs)

[ehird]

~: It's hardly simplistic when the linux coding guidelines dictate that a function should generally not exceed 24 lines, and that any more than 3 levels of indentation means you probably are doing something wrong.

That's more harsh than my assertation.

mystran: Interestingly, I don't tend to be any less productive with minimal editors.


"sam" and "acme", two plan9 editors:

* sam cannot auto-indent
* sam does not let you use the cursor keys/other keys to control mouse position. Ctrl-A|E for start|end of line, and the cursor for the rest, is all it allows.
* No syntax highlighting in either.
* acme's autoindent is very dumb: "if previous line has tab characters in, insert the same number when enter is pressed". No more.
* sam is built on ed - at the top is a command window where ed commands (therefore regex replacing/searching/etc) can be entered.
* acme only lets you brace-match as far as right-clicking on a word or some highlighted text jumps around the file, highlighting each occurance of the text and moving the mouse to it. So you'd have to do:

{|
blah
}

type }:

{}
blah
}

right click:

{}
blah
}|

then remove the } after.

yet I find them to be very fast to edit any kind of code with. Both of these editors, however, allow you to manipulate output from arbitary command-line programs to modify text - so whenever they don't implement something, I just use that.

++ on the grep suggestion though

</long rambling rant>

[mystran]

~: It's hardly simplistic when the linux coding guidelines dictate that a function should generally not exceed 24 lines, and that any more than 3 levels of indentation means you probably are doing something wrong.

Those are just guidelines. If you actually bother to browse the source, you'll see that they are broken all the time. But I must agree that often when you've got long functions, or need lots of indentation, you should at least consider structuring the code differently. My experience is that it also tends to lead to better code quality in general, allowing more flexible error handling and less duplication of functionality.

Every programmer should learn to ignore the fear of restructuring. We tend to think that restructuring some code is a huge amount of work, when most of the time it's simply a case of some copy-pasting, minor rewriting, and some search/replace. It's almost always possible to keep the interface the same, or change it very little, by providing interface wrappers for the actual implementation. The important thing is to export only the wrappers, so that when you have to restructure your code next time, your interface hasn't suddenly grown uncontrollably.

Linux is pretty clear code in this sense. It's just the details that looks a bit intimidating when you try to read it, but the problem is simply that it's written in a style where every line counts, so you actually have to read and understand every line. Once you accept that, it'll be a lot easier to read Linux sources.

mystran: Interestingly, I don't tend to be any less productive with minimal editors.

I'm willing to suggest that you've never really bothered to learn any (of the two) powerful editors properly. I thought the same until I watched a friend hacking in Vim.

yet I find them to be very fast to edit any kind of code with. Both of these editors, however, allow you to manipulate output from arbitary command-line programs to modify text - so whenever they don't implement something, I just use that.

That'll help a lot if you're in Unix-like system (and plan9 is supposed to be more Unix-like than Unix itself, if I've understood correctly). It makes little difference whether you run regex replacing using the editors own engine, or pipe the stuff to sed. I'm under the impression that plan9 was specifically designed to bring back the original Unix idea of having programs only implement original functionality in small pieces, and then call each other to borrow that functionality into new contexts.

[ehird]

I'm willing to suggest that you've never really bothered to learn any (of the two) powerful editors properly. I thought the same until I watched a friend hacking in Vim.

Nope. I've learned both vim and emacs at various times. I'm not a fan of them:

- Vim emulates a lot of gui stuff inside a terminal - that's just backwards. Vim's graphical interface is basically a terminal emulator with buttons.
- Emacs reimplements unix on top of unix - all those purpose-specific programs combined and forced inside parentheses.

But let's not start an editor war here of all places, mm?

[Alboin]

* acme's autoindent is very dumb: "if previous line has tab characters in, insert the same number when enter is pressed". No more.

I used acme for some things. I thought it pretty nice. (The using of the mouse is surprisingly useful.) It's just that plan 9 has the ugliest GUI I've ever seen, and the Linux port doesn't improve it.

As for the point of the thread: I think the whole 3 lined comment repeat actually decreases code readability, and makes the code look bulky.....sorry.....I like light and flowing code that is very short in width. I can't stand that stuff Microsoft puts out.

Code: Select all

H_UGLY_POINTER *g_BlahBlah = H_GetMeow(g_KLFDSFS, 273498234, 0x34567, *g_WhatAmI);

Really, If I had any say over there, I'd demand that all caps lock keys be removed from all the keyboards.

Yeah...okay....toodles..

[ehird]

Plan9's gui is an artifact of the 90s that nobody's worked on recently.

I'm working on porting libdraw (the drawing lib plan9 uses) to OS X right now...