Recent Posts526
General Software Discussion / Re: Good coding conventions - Discussion
« Last post by Jibz on January 03, 2013, 07:47 AM »When it comes to naming conventions, I largely adhere to when in Rome. Personally, I prefer lowercase with underscores. I am not terribly fond of Hungarian notationw -- I feel 90% of the time it is extra typing with no benefit. I can see some benefit in CamelCasew for long names, as long as your editor has some kind of auto-completion, but like f0dder puts it:
I must admit, I am a big fan of comments
. I believe commenting the "intent" of your code is usually worth it. There is not a lot of code outside of textbooks that is really self-documenting, and what seems obvious to you while you are writing the code may take a little time for the next coder (or yourself in a month or two) to figure out. Reading a short line of text is always easier than interpreting a few lines of code. Also, when you look at a function, I think it is a lot easier to grasp what it does if you can skim over it only reading the comment lines (which most text editors highlight in some way), and that gives you a kind of "storyboard". As an example, if you take this simple function
and only read the comments you get
which sums up what it does. Granted, the single lines of code in that particular example are so simple here that you could probably easily understand the function without the comments if you know what the API calls do, but I am guessing it would still take you at least twice as long as just reading the comments.
And like you say, always make a comment about any hackish code, because even though you know how it magically does what it does right now, nobody (including you) will know in a month
.
I like and use the ternary operator as well, in some situations it lets you express more clearly what you want in less code. Of course you can make unreadable code with it as well, but it's always like that (with great power comes etc.
).
Btw, I don't know if it's GeSHI or Chrome, but it looks like most of the identifiers are raised a little above the line (or the operators and keywords lowered) in the code blocks, which is slightly annoying to read:
If you end up with method names that are long or weird, that's often a good indication of a code smell.-f0dder (January 02, 2013, 03:44 PM)
I prefer well-named and small (private) functions/methods over comments. Comments are fine for documenting your public APIs, as well as some implementation details, quirks and hacky workarounds - but other than that, I prefer to split into small and well-defined steps, and let the code speak for itself.-f0dder (January 02, 2013, 03:44 PM)
I must admit, I am a big fan of comments
. I believe commenting the "intent" of your code is usually worth it. There is not a lot of code outside of textbooks that is really self-documenting, and what seems obvious to you while you are writing the code may take a little time for the next coder (or yourself in a month or two) to figure out. Reading a short line of text is always easier than interpreting a few lines of code. Also, when you look at a function, I think it is a lot easier to grasp what it does if you can skim over it only reading the comment lines (which most text editors highlight in some way), and that gives you a kind of "storyboard". As an example, if you take this simple functionCode: C [Select]
- BOOL sut_open(SUPTIME *sut)
- {
- wchar_t szCounterPath[PDH_MAX_COUNTER_PATH + 1];
- if (sut == NULL) return FALSE;
- /* construct path to localized system up time counter */
- if (!make_counterpath(szCounterPath, sizeof(szCounterPath) / sizeof(szCounterPath[0]))) return FALSE;
- /* check path is valid */
- if (PdhValidatePath(szCounterPath) != ERROR_SUCCESS) return FALSE;
- /* create query */
- if (PdhOpenQuery(NULL, 0, &sut->hQuery) != ERROR_SUCCESS) return FALSE;
- /* add counter to query */
- if (PdhAddCounter(sut->hQuery, szCounterPath, 0, &sut->hCounter) != ERROR_SUCCESS)
- {
- PdhCloseQuery(sut->hQuery);
- return FALSE;
- }
- return TRUE;
- }
and only read the comments you get
Code: C [Select]
- BOOL sut_open(SUPTIME *sut)
- {
- /* construct path to localized system up time counter */
- /* check path is valid */
- /* create query */
- /* add counter to query */
- }
which sums up what it does. Granted, the single lines of code in that particular example are so simple here that you could probably easily understand the function without the comments if you know what the API calls do, but I am guessing it would still take you at least twice as long as just reading the comments.
And like you say, always make a comment about any hackish code, because even though you know how it magically does what it does right now, nobody (including you) will know in a month
.Use of the ternary operator doesn't mean I'm in the "as few lines of code as possible" camp, though. I often break condition of if-statements into (properly named) booleans or method calls, which obviously results in more code lines... but also in better readability.-f0dder (January 02, 2013, 03:44 PM)
I like and use the ternary operator as well, in some situations it lets you express more clearly what you want in less code. Of course you can make unreadable code with it as well, but it's always like that (with great power comes etc.
).Btw, I don't know if it's GeSHI or Chrome, but it looks like most of the identifiers are raised a little above the line (or the operators and keywords lowered) in the code blocks, which is slightly annoying to read:
.
