What are the best practices?

[mirv]

My pet gripe actually applies to the willy-nilly (technical term) application of printf in embedded C environments. The stdio library, and associated others, are rather (read: insanely) large for the severely limited resources of embedded systems. That, and it's useless in most cases (although some systems redirect such output to a serial port). So I guess that turns into: use your selected language as it's supposed to be used. VHDL (for any that have dabbled in it) shouldn't be treated like C, C shouldn't be treated like Java, etc etc etc.
Fairly obvious, I know, but my workplace doesn't always believe in such things as common sense.

Other than that, I'll second things like keeping a constant coding standard, don't let comments outweigh the source code (note that I distinguish between comments as meant to better understand code flow, and "comments" that are really documentation). And if code smells bad, it probably is.

Interestingly enough, I have to create a presentation on embedded programming guidelines for students now.

[stefanhendriks]

Granted, each language has its public and should not be forced to be used in a way it is not designed.

However, Java, and C++ for instance are very alike and can be treated the same. But, on the other hand you should very well know the differences.

As for comments, i love javadoc, really.

/**
* This is a comment that will show up in a HTML generated file, and with Eclipse it automaticly pops up when i hover my mouse over the function/method
**/
void someFunction() {
 // do something
}

[mirv]

Stumbled across this (some thoughts on when to document code), thought it could be a little relevant to this thread:
http://www.gamedev.net/community/for...ar=2008&cday=9

[stefanhendriks]

Originally Posted by mirv

Stumbled across this (some thoughts on when to document code), thought it could be a little relevant to this thread:
http://www.gamedev.net/community/for...ar=2008&cday=9

Lol. Commenting after a period of time to enforce code reviewing. It is a view i can share for some parts of it. But you actually have to take time for that; normally commenting is done 'within coding'. Meaning, whenever i get the order to code something, i do comments with them. Not only because it is 'fresh in memory', but also because i know there won't be a next time.

The only times i do add comments to pieces of code that i did not write in the first place, is code i need to touch anyway.

Good post though!

[TomTom]

I like there to be lots of comments in code, I just don't like them cluttering up the lines too much (you can always indent end of line comments to keep them away but some editors don't do wide, and it always screws the printing on paper.) What I have wanted was an editor that interpreted the comments and selectively printed/displayed them. Say after each comment was an "escape" character that described the importance of the comment say //\1 could mean level one comment and //\3 would mean level 3 comment. The editor would only show the comments above a settable level and would color the "escape" character to be almost invisible. ( Codewright had lots of programmability but I doubt it could handle that). And if it could handle hyperlinks in comments then lots of documentation could be in a separate file.

Constant coding is very important but bosses rarely do more than lip service. I worked for a company that at one point hired 1 student on work study for every 1.5-2 permanent coders. Absolute mess, the students declared variables wherever they cared to, used Proposed ANSI C styles that the older compilers could not support. They never spent time on the coding style documents, did not know a linker, linker command file or map file from a hole in the ground.

On your embedded point, sprintf is important printf is not in my experience, and you need one of the smaller libraries that can be split up if you have to squash memory. Of course format strings are dangerous in embedded, you can leak and not know it in C so easily (Wolfenstein ET is a good leaky game coded in C). Mind you TI code composer studio had a neat way to output a printf for debugging. They put an index and parameters in 1-4? 32 bit words in memory, then using the idle manager time the pod would pick up the data then match the index up with the constant string in your printf then format and print that string on the debugging PC. No need to format in the target that way.

Don't you mean Verilog should not be treated as C, which it shouldn't...

[mirv]

Nope, VHDL. It's what I use at work. Shouldn't be treated like C - problem is that at first glance you sort of can, just that a) there's no point, and b) it gets confusing.
On a side note, I also steer clear of any form of dynamic memory management in embedded systems (at least with the stuff I do) - when you only have 8kB of memory to work with, that's not really an option.
But I'm deviating from the main topic - any further discussion on embedded programming should probably be moved to a different thread.

I also put in areas of code to cause compiler errors - for example, if I'm changing a few interfaces, I might just put a single line:
errortime;
That causes the compiler to stop. Makes sure that I don't forget to change things later. Don't know if that's really a "good" practice, but it helps me sometimes.