OSDev.org

When you've written your OS drivers in the past, is there an etiquette you've used pretty thoroughly throughout your project? Is there a standard -- something akin to the variable-naming convention of szString, iInteger, cChar, and so on -- that I should be aware of?

My IA-32 rendition of my OS is being built in pure assembly and I've just hit the USB stage because I want to load binaries now. Oh hell, what an interesting journey these past few days have been! In my source code, I have been taking a real preference for naming my assembly functions from largest scope to smallest. For example, the function USB_UHCI_DEBUG_outputPortVariable is a function for the USB driver, is UHCI-specific, is only to be used as a helper/DEBUG function (so I know I'm doing the right thing and can test different values), and it outputs a read on a specific port from a controller's BAR4.

I ask this question for two reasons:
1. Whenever I make friends with a contributor, I want him/her to stay sane!
2. If there is a convention of sorts, I would like to follow an industry standard so that this project lends itself to being 'work experience' for my CV.

I am honestly really amped about getting file transfers and data reads going, finally. It's still a long way off, but just being able to recognize when device connections change is huge!

First... congrats on your file transfers....!

There are many many different coding style guides out there... variable naming be just a subsection; there are guides for indentation, for docs, and obviously API/ABI

In my humble opinion... choose something that makes yourself happy... you are they person who has to look at it all the time...

If and when you start to get 10's of contributors - a formal guide for them would be a plus - so check out some of the coding styles for such projects as VTK (vtk.org)

The only thing I cannot stress more than enough is NEVER USE C++ KEYWORDS as variable names....

so don't call a variable "new" or a function "class" etc.... if your stuff takes off then someone will use C++ on it somewhere along the line and this kind of naming is in infuriating...

cheers!

human00731582 wrote:Is there a standard -- something akin to the variable-naming convention of szString, iInteger, cChar, and so on...

...which is utter donkey manure.

What you are referring to is called "System Hungarian", and it is what happens when mediocre coders hear of a principle sound in a different environment, misunderstand it, misapply it, and generally make a mockery of it.

If you are coding clean C, the type definition of your variable is quite close to hand:
So what does adding a "type wart" do?
It duplicates information that is already there, and obfuscates another bit of information (what the actual variable is about, "number"). It also makes communication more difficult, because you will either stumble your tongue over the type warts (only one or two characters, but usually just as many syllables), or omit them, and thus lose precision of meaning.

When Hungarian Notation was introduced by Charles Simonyi, it was about adding information that is not there already:
rwNumber is a ROW number. xwPos is the x position relative to the window, and ywPos is the y position relative to the window. All ints. None of them interchangeable.

Unfortunately, Simonyi talked about "type" of variable, not "kind" of variable (which is what he meant) when he presented his paper, and when the idea spread beyond the team Simonyi worked in (the "apps" team), people took "type" literally, and "Apps Hungarian" became "System Hungarian", the crap idea of prefixing every integer with "i" and every string with "sz" and so generally making a mess of readability with information that is redundant if you're lucky, and inconsistent if you're not, but serves no practical purpose other than making identifiers longer, and harder to read / talk about.

Or, to quote from How to write unmaintainable code: "Hungarian Notation is the tactical nuclear weapon of source code obfuscation techniques."

Apps Hungarian can serve a purpose in dynamically typed languages, is borderline useless in typed languages, and a complete nuisance in strongly-typed OO languages like C++. Don't infect yet another code base with it, even Microsoft have deprecated the idiom years ago (both System and Apps Hungarian)...

---

Now to find the two chaps who couldn't decide whether every C++ class should be prefixed with "C" for "class" or "T" for "type" and made the code base I am working with such a fun experience...

Hi,

Solar wrote: What you are referring to is called "System Hungarian", and it is what happens when mediocre coders hear of a principle sound in a different environment, misunderstand it, misapply it, and generally make a mockery of it.

Oh, this brings back hellish memories of working with MFC and C++ DirectX interfaces in Windows 98. Years of counselling trying to push those memories from my mind wasted

Cheers,
Adam

don't let others impose their preferences to you. As chapiesky said, choose that style you are comfortable with. and that's all, everything else is a waste of time, this jabbering on style is a sign of a dangerous distraction. you either are doing your project or jabbering on style, intendation, language choice, participating in endless microkernel vs. picokernel debates etc...
someone's else tastes are not relevant here. I see Hungarian notation haters showed up. I oppositely like it and think it's useful. It's all tastes no more.
Examples:
naming_function_style_i_hate();
NamingFunctionStyleILove();
Style_I_Can_Not_Stand();

If someone is tryna convince you one of them is genuinely better than other, then smile and do by your own mind. Because unlike "interrupt handling" or alike questions, this is a pure aesthetic thing you only could deal with by yourself.

Of course code style needs to suit you. But you should always consider that, if your project actually takes off, or you want to post code somewhere to get help with a problem, people shouldn't have to use Rosetta stones to make heads or tails of it. Also, if your system is open source, your code style will be remarked upon. And even if closed source, your system headers will set an example for any user-space programmer.

So code with consistent indenting / bracing, consistent naming scheme, and the good kind of comments that goes beyond repeating the obvious, is objectively easier to read in general than code without.

Indenting and bracing, there's code beautifiers for that (AStyle, for example) if you don't have a consistent writing style anyway. They can even be plugged into the commit / test cycle. Naming scheme, pick one and stick with it. Personally, I prefer a naming scheme that is halfway consistent with the language's standard library because you will be using either in the same code base. If the styles clash, the code looks ugly.

Comments... If you've ever worked code maintenance, you know what you would have liked to be in them. Just as with identifiers, use English. Localized identifiers / comments are... not that good.

Just be aware that many very competent software architects and developers have spoken out against System Hungarian, including most of the people at Microsoft who had to work with it for several iterations of Windows.

As Solar says, your code style needs to suit you but for C++ I find the (elderly) guidelines here to be quite agreeable as far as legibility is concerned.

Cheers,
Adam

For C++ specifically, there is "the book" on the subject that goes far beyond "style". Sutter / Alexandrescu, it doesn't get more authoritative than that.

@Solar: Thank you for the discussion of Hungarian notation. I was about to launch into a similar tirade when I started reading the thread, and you ninja'ed me with an explanation far better than any I could have given. Bravo.

As for programming style guides, the main considerations are:

• Consistency - if the style guide is inconsistent, or the code doesn't follow it consistently, it is useless. However, this includes knowing when it is better to be inconsistent rather than make something ugly, confusing or impractical to follow. It is not an easy thing to do, and often has to be done on a case-by-case basis, so it is better to leave some wiggle room without letting the whole thing get thrown away - not an easy feat.
• Practicality - it shouldn't ask things of yourself or others which aren't feasible over the long haul. You need to take what people can do on a consistent basis into account.
• Simplicity - the difference between too few guidelines and too many is as thin as a knife's edge. You need to consider every rule and ask if it is really needed or not.

There is more, a lot more, but these I think sum up the general problem in making and following a style guide. The best advice I can give is to look at those which are already available - you should be able to find several with a basic web search - and either select the one you find appealing, or use them as inspiration for writing your own.

Whatever the style is, as long as the team participating in the project adheres to the same standard and work as one, it will be great. What is insane, is different people each pursuing their own standards negating each other's work. At any enterprise size company, it is a huge problem, very difficult or impossible to enforce the convention due to many substandard engineers has ascended to a position of power and influence, for smaller companies, it seems the standard is enforced pretty easily. At least that is my observation from the past. That is one of the biggest advantage of working in compact, smaller company. My 0.02$.

@Schol-R-Lea:

*bows*

Thank you.


@ggodw00:

Take a look at JAWS. Or, more precisely, this two-file subdirectory of that project framework.

What you see is a source file (check.cpp.in), which (after very minor preprocessing by CMake, hence the .in) gets compiled into an executable.

This executable is added to the test cases for the project. Given a start directory (defaulting to the source directory of the JAWS project), a list of source file extensions (.cpp, .hpp, .java, ...), and the configuration from check.cfg (the other file in the directory), it executes the following operations on each source file in the project (except those listed as exempt from testing in check.cfg):

• checking file name length
• checking file name for unwanted characters
• checking the source for unwanted characters (basic character set, a subset of ASCII-7 -- yes I know most compilers accept UTF-8 these days, but some don't, and some editors are running with weird options regarding charset, so better be safe than sorry)
• running the AStyle code beautifier on the source (using the options from check.cfg), and if making changes, writing the changed file to <filename>.reformatted

The first three tests, if failing, result in clear error messages as to the exact nature of the failure.

If any of the four tests fails, the whole test fails for that source file.

The last test will be skipped if AStyle is not installed on your machine, or not in the required version (to avoid two different versions getting into a formatting war over commits). The "master" version is the one on the continuous integration server (you are using one, aren't you?) doing these tests whenever source is committed to the repository.

So, if you run the test suite, all of the above is automatically done as well (which takes <2 seconds on my 9-to-5 source base). Any source file failing the test gets reported, and you get a big fat red square on your continuous build dashboard. (You are using one, aren't you?)

No modifications are done to the source file automatically, mind. Even the reformatting just results in a second file you can diff against, in case the source reformatter (AStyle in this case) did hickup or something.

This pretty much enforces a certain "style" automatically, while at the same time helping you to achieve it (just run the test locally and make necessary changes before committing), and teaches whomever is working on the project what that style is by making violations visible (instead of automatic apply-and-commit).

I, personally, have always prided myself on pretty clean code, but it got even better once I started this scheme. I very seldom run afoul of AStyle reformats anymore. You can make the options as tight or as relaxed as you like, of course, but I found the options I did set as default to greatly increase readability.

The program could easily be expanded to add more tests, e.g. checking naming conventions. There are tools for that out there, and you can plug them into the test scheme easily.