by Doug Coulter » Wed Jun 22, 2011 9:33 am
Yes, I like to align braces too, but I use "short" tabs for indenting because I like to keep lines short enough not to wrap on a standard printer page. Several of the editors I use will help with that "prettifying the code". And most will let you put the cursor on one brace or paren, and will then either jump to or highlight its matching one for you. I'm a big believer in color syntax highlighting, and usually set it up a little more garish than the "stock" settings. I make my comments the color of money, because that's what they are down the road -- many editors default to making them light gray or italicized - I don't like that, if anything they should be the most visible. Further, I comment braces, particularly the closing ones -- "this is the end of the for i loop" kind of thing. When a brace pair is separated by more than a single displayable page, this really pays off in fewer mistakes.
Keeps things from getting too messy when at the end of something there's three or more closing braces for nested if's and while loops.
When things get deep, I only indent one space. I've never liked putting the opening brace on the same line as the thing that starts a block -- I like putting it on the next line so the indents can match with the closing one -- and I comment both.
Example:
if (some hairy test of something)
{ //handle case of hairy test being true
// some code here
} // end of handle particular hairy case
I use the following scheme usually:
Keywords/builtins -- bright blue
Strings - purple (makes it real obvious when you forget a quote)
Numbers -- red, because using a number is bad programming practice -- use a define instead so it's easy to find, comment, and change for the whole file/program.
Comments -- color of money, and there's nothing wrong with having more of them than code
I use the block comment style at the beginning of routines I supply (like say the rs232 stuff, or the LCD stuff) with some fairly detailed stuff about how to use it, what to avoid, what it does under the hood. This helps work with a team.
If there's a call with a ton of parameters or it's just real long, I will break up the line into a couple, aligning the next lines with the opening paren of the call. This can be dangerous if there's anything past the line break character, some compilers get messed up with that one and if the "bad" character is a space, you can't see it. In Gedit, this is nicely fixed by having it show whitespace characters -- spaces are gray periods and tabs are little gray arrows. For some things there's a big difference. I recall some MS stuff where it had to be either spaces or tabs (idiots didn't know how to look for whitespace in whatever form). Some makefiles are like that, and some of the junk in OLE specifications. It can be a big issue if your editor automatically changes spaces to tabs or vice versa. When I can, I use spaces -- because depending on things, a printer or another editor might not have the same tab points and it will look terrible on another platform or printout. I DO really like color syntax highlighting for the rare times I have to print something so I can study it finely, but sometimes the colors that look great on screen stink on paper and you have to adjust.
I put my includes up top -- commented for why they're there, then global variables and structure definitions, things like that, then subroutines, then main at the end. This is just my convention, but it makes things easier to find, and dependencies clearer, while reducing the need for forward declarations (less noise in the file).
On real big and complex projects, I'll use my own form of Hungarian notation for naming, but I'm sort of lax about that. I will often put a g as the first character of a global, or an i for a variable used mainly by an interrupt. Perhaps a b for a boolean (matters in a pic where a bool is one bit and can't hold a real number) I rarely (anymore) use characters to describe the type of variable (char, integer, array, struct, float) because I really hope I've made that obvious another way and I like readable names. I use all uppercase for most defines -- makes them stand out when used, and in that case use underscores between words in a name. The rest of the time I use selective caps to make the words more readable, but this one some people don't like. I just don't like having to find the underscore key all the time as it's harder to touch-type quickly, though I should say that cut and paste are things I use a ton. That lets me use reasonably long and hopefully descriptive names more. As the ancients used to say -- there is a lot of power in a name, and you should really put some upfront effort into that, it will pay nice dividends later -- and if you find yourself not liking a name because the design shifted -- then you get a nice flag that you need to acknowledge that and re-think and maybe re-factor some. Some are easy -- SerialOutputBuffer should be clear by itself, for example.
Some advanced editors will have both multiple clipboards for cutting and pasting (which can save some hassle if you need to grab more than one thing and move it to more than one place, say in another file) and also templates. For example, something I use a lot might be "for (i=0;i++; i<?) {}. Some editors will let you pop that in with one keystroke, and put the cursor on the ? for you to fill in. And yes, I use i all over -- to me it means "iterator" and many of my programs just define i,j,k for that use (shades of fortran).
These are mostly style things -- but style can matter both for working with others, and for when you revisit code a long time after you've written it.
I think doing things this way gives you the best "force multiplication" out of the system. The more you can have the compiler detect errors, and make them instantly visible to a quick visual scan, the less time you have to spend "in the trenches" digging for junk. No compiler can catch conceptual errors, that's on you -- but I even get a leg up on that the with naming - if I find myself using a name that doesn't "look right" in use -- I know I've screwed up my organization somewhere along the line. I like it when I can read the lines and they are almost sentences that make sense -- the code should probably flow into the comment like you're making a statement (which you are, after all). While the coupling between beauty and truth is less tight here than in advanced physics math, it's there.
Always remember that none of this makes the code going into the target any bigger or slower (assuming you designed it right in the first place). It's fine to have a huge text file that compiles down to diddly, the PC where that part lives can hack it easy, and anything whatever you can do to make the code more readable and easier to work with later is well worth it. Especially when you want to grab some little tidbit out of it for the next project...the longer you do this, the bigger that nice old bag 'o tricks becomes, and the faster you can get good results using already known-good chunks of code.
Posting as just me, not as the forum owner. Everything I say is "in my opinion" and YMMV -- which should go for everyone without saying.