Developed on Hackaday: Coding Conventions and GitHub Pull Requests

The Hackaday community is currently very busy coding the low-level libraries of our open-source offline password keeper project. And when many talented contributors work together on a common concept, interesting discussions take place. In our dedicated Google Groups, some of them were about the choice of naming/coding conventions and also how/when to approve GitHub pull requests. But don’t leave already… this topic is actually more interesting than it sounds.

The age difference between the older and younger firmware contributor is guessed to be approximately 30 years… and many things can happen in such a time frame. Even though our coders are writing in C, most of them code in other programming languages at school/work. They also use different text editors on different operating systems. Understandably, each one of them therefore has its preferred coding / naming convention and indent style. The Mooltipass conventions were selected based on majority voting, and after many emails we settled on an Allman style convention with camelCase:

main(void)
{
    if (foo)
    {
        functionCall();
    }
    else
    {
        foo = 0;
        anotherFunctionCall();
    }
}
- 79 characters line length as a soft requirement
- 4 spaces, no tabs

Most of the contributors believe that it is the best compromise between code clarity and cross-platform compatibility, but we would be curious to know our Hackaday readers’ opinions on this particular topic.

The second matter is a bit more of a management one. What is the best strategy to manage and review code changes made to a main GitHub repository, when a project is at its infancy and composed of (more or less) non-remunerated contributors?
It is perfectly understandable that interest, spare time and willingness to contribute may vary over time. Perhaps some of our readers may already be familiar with Agile software development, a group of software development methods based on iterative and incremental development, which promotes adaptive planning, evolutionary development and encourages rapid and flexible response to change. Do you think this can be applied to the Mooltipass project?

We would be curious to hear similar experiences on these topics, as we gladly accept constructive criticism. You may also want to join our dedicated Google group to check out the different discussions that already happened there. On a side note, we are also currently looking for capacitive wheel / touch button footprints libraries for Kicad.

100 thoughts on “Developed on Hackaday: Coding Conventions and GitHub Pull Requests

    1. Allman style is my preference as well. Allman-style source code is the easiest for me to read through as blocks of code are easier to identify. Someone below complained about wasted space, but I don’t see why that’s an issue.

      1. {} line up and tells me it’s a scope. The only issue would be in javascript and you are not “compressing” it. But if you site is bogged down just because of that, something is seriously wrong.

  1. There are some benefits to a 79 character line limit, but I’ve found it to limit the ability for programmers to use descriptive names. I hate when people use arbitrary abbreviations in function and variable names.

    1. I see little benefits, and I see lots of problems. Someone trying to enforce a character limit on my code would be killed by me. Slowly.

      An soft indentation limit, I can see how that is useful.

  2. Strongly prefer K&R, but more to the point, wouldn’t bother working on a project with enforced formatting requirements…

        1. When you get multiple contributors all using their own styles all in a single file, that’s not a coding style.

          With coding conventions it usually doesn’t matter too much which convention gets chosen, just so long as everybody in a project sticks to the same one.

        2. When you’re a real programmer, you understand that consistency within a project has actual, real-life benefits for that project, unlike posturing over who isn’t and isn’t a real programmer.

          1. To elaborate, it hardly matters what the style is, as long as it isn’t reverse Polish Christmas tree. There are few things worse than a room full of people arguing over goddamn bracketing styles. There have been points in my life where I have literally said “I don’t care which style we use, just fucking pick one. ONE.”

            Same goes for tabs vs spaces. No one will ever “win” that stupid “debate” and nothing is to be gained by continuing it.

            Sooner or later it all comes down to preference, so the best thing to do is take a simple poll, one with radio buttons, and then have someone with autocratic power make the final decision. I defy anyone to find a would-be contributor worth a damn who was driven away entirely by style guideline minutia. Meanwhile, people give up on open source projects every day due to code bases being inconsistent trash piles.

          2. Am I the only one disappointed to find out that “Reverse Polish Christmas Tree” is not a real coding style?

        3. Am I the only one who sees the idiotic hypocrisy in your comment? A “real programmer” will also have to adhere to project and company conventions.

    1. It takes time to find that @#$^ open bracket at the end of a conditional if. So much easier to match it up when it is vertically aligned with the closing one. As I have said in my last post, I came up with something similar to Allman style on my own for consistency across languages.

      I won’t bother with K&R code unless real money is involved.

    2. Maintenance of code is far easier if coding style is consistent. The issue of writing new code vs maintaining existing libraries is where coding style matters. I’ve seen projects where beautify is forced before any code is checked in, to avoid this issue.

      I’ve also seen uncontrolled styles where K&R, Allman, and all sorts of variable notation is used (including different variants of Hungarian notation in the same code). Annoyingly there was a mix of indentation: some used tabs, others used 2, 3 or 4 spaces, all in the same code. We’re not talking separate programs here. The worst issue would have to be that some devs decided to apply their own beautify each time they modified any existing code (even if all they did was change a handful of lines). Kinda made diffs difficult.

      So when the number of people that may touch the code exceeds anything larger than a single scrum (say around 8 to 10 people), then I would suggest that enforced standards greatly assist in the cost of maintaining the code. While I understand using beautify to enforce standards, I would rather code acceptance/inspection as the mechanism to enforce standards. We’re all mature adults here (I hope).

      Personally I write in the style of the code that I’m editing. If I’m writing new code in an existing project then I will check what is in use and use that. While my preference is for 1TBS, it doesn’t overly bother me which style is in use. An any mature developer should be able to adapt their style for the code that they’re editing IMHO.

  3. I don’t care too much on naming conventions, newline curlybraces, spaces around parameters in brackets, line lengths and all that stuff. I’ll just follow the style of the file I’m editing (It does become difficult with a file already edited by multiple people with multiple conventions).

    One convention I HATE is spaces instead of tabs for indenting. if you want 2, 4, 8 or even 3 or 7 spaces, you can set that in your Editor/IDE. If you can’t then use an editor made this decade!
    If you must align things after the initial indentation then fine, use spaces.

    1. Tabs are problematic, especially when mixed with spaces. It takes a lot of effort to find the correct tab to space ratio, if any.

      1. Every time you refer to “some_variable” instead of “x” you’re wasting like 12 bytes. Why use tabs at all? That’s wasted bytes for a non-essential feature!

        Seriously, this is the dumbest argument I’ve ever heard in a tabs-spaces debate.

    2. +1, especially tabs vs spaces

      – Whatever’s in the file, but it’s always good to have a standard, so the file tends toward consistency.
      – Most important is the quality of documentation, both inline and for automated doc generation.

  4. What a waste. A whole line just for one curly brace that could easily go at the end of your if() statement.

    I’m not a big fan of camel case; I prefer underscores and all lower case unless a specific function requires otherwise.

    Tabs/spaces. *shrug* Indent 2 or 4, but never more.

    In all instances, ignore coding guidelines from the Linux kernel dorks. :-)

    1. The waste of vertical space argument is void & null (pun intended) if you put the open bracket on the first nested statement.

    2. wasted space? what space? It’s an extra byte or two in the source code (sure it adds up, but not to much). A little bit of vertical space on your monitor? You can scroll.

      hiding your braces on lines with other stuff is a terrible idea. it can lead to issues similar to the recently publicized goto fail; https://www.imperialviolet.org/2014/02/22/applebug.html

      (similar to, but not the same, that bug wasn’t because of braces).

      if using the extra space saves a single bug, it’d be worth it.

      1. Sure you can scroll…. But it’s always good to see more parts of the code around the lines you currently working at.

        If wasting a lot of lines with just an empty start-curly doesn’t bother you then maybe you would also accept having a few completely blank lines above and below each code-line – because “you can scroll”? Hmmm…? I didn’t think so. :-)

        Not everyone is sitting at a 24″ screen with 1600 pixels height – a lot of people use laptops with a crappy 768 pixels in height… Then every line is precious.

      2. Ehh, the Apple bug kinda was because of braces… when I’m teaching programming, I encourage the rule that braces should always be used in any construct that will admit additional statements – so the conditional clauses following the ‘if’ statements in Apple’s example would have been braced, and the bug would have been obvious (or would not have manifested itself).

        1. We use the same standard where I work. Yeah braces add lines, but this is isn’t a terribly convincing argument if even a few man hours are spent dealing with bugs that result from this sort of stuff.

      3. No, that bug was caused by NOT USING BRACES IN THE FIRST PLACE.

        if (foo) {
        blah();
        } else {
        baz();
        }

        ALWAYS. Stupid Linux coders.

    1. I work as a full time developer, and I’ve worked in open source projects. At work we transitioned to an agile methodology just over a year ago, the transition was tough for some people, especially those who had worked in the previous system for a long time.
      I think agile *could* work for an open source project, but you’d need quite a lot of oversight. I have no idea how you’d attempt to do work estimates in such a situation. Nor do I have any idea how you’d encourage people to work on the issues that you select.

  5. Been using the Allman style before I knew there was one back was when K&R was the final word on C. It was just something that I have to do to cope with all the different languages that I have to learn and use for each CS course.

    Camelcase or not doesn’t matter as long as there are no SMS Text Abbreviations (IMHO Aberrations) as I recognize shapes of letters and having to spell things out slows me down.

    Not that it matters much to me as I do not work with open source stuff that frequently. I mostly write my own code (without framework/library) as a hobby and for supporting my hardware. It takes more effort to understand code that are written by multiple people each doing things a bit differently than to write my own code.

  6. IBM once studied the effects of coding style versus bug frequency. I don’t have a link, since this was before the internet.

    Their conclusion was that number of bugs per line of code is a constant regardless of language, but was affected by the number of lines that the coder could see in one editor page.

    Specifically, coding styles that show more lines per page resulted in fewer bugs than coding styles that use lots of vertical whitespace. This held true up until the “obfusticated code” limit where people started to have trouble understanding the code.

    Let’s make that more clear: A particular coder tends to have N bugs per 100 lines of code (IBM estimated that the average N is 4), and this number is the same whether the coder is working in assembly, C, or APL. Being able to view more code at once reduced this number.

    This is a religious issue among many people, but if you want to judge based on evidence and studies, the conclusions were:

    1) Lines longer than 80 character sometimes avoid breaking one line into two
    2) Use vertical whitespace sparingly – avoid unnecessary braces (single-statement if, while, &c) and blank lines (but break the code into paragraphs for clarity)
    3) Tuck opening braces onto their defining statement (subroutine, if, while, &c)
    4) Use expressive languages so that fewer lines will express complex concepts. Assembler is less expressive than C, which is less expressive than Perl.

    This is a separate and disjoint topic from coding clarity. Coding clarity was found to be an aspect of the coder, and not the language or style. That is to say, one can write clear code or difficult code in both perl and C, and using any coding style. Some would argue that perl makes it *easier* than C to write obscure code, but as perl is more expressive the perl program uses fewer lines so it will have fewer bugs.

    Let the religious wars commence!

      1. Try to keep in mind the difference between a study reporting results averaged over a large sample space with an single anecdotal instance that affected you emotionally.

        1. I see no citation to a study. you comment has no more credibility than mine. But feel free to just tout your line instead of contributing further to the discussion.

      2. +1 I don’t like single line If’s, I know one day I’ll write a line of code below the first and introduce a bug.

        The tenary operator can be useful for keeping things on one line though.

    1. This is a big plus for folding editors, I used to really like those as once you had sorted something you could close it and know that it was OK in there. Transputers used to use folding editors and they were a brilliant concept.

    1. Are you all discussing something that you don’t know what it is or is it that no one can be bothered to answer?

      I sussed camelcase but Allman is eluding me. Who thinks up names for these things and why is it a point worth discussing, don’t you just do what you find easiest to read afterwards.

      Wherever I have a “}” there will be a comment telling me what it is the end of along with the name of it and its corresponding “{” will have a comment telling me what it is the start of. I think if everyone did that people could understand other people’s writings a lot more easily.

      Being predominantly an assembler programmer I am really good at making making variable names and labels, mostly without vowels that you can read. << Linux tradition that methinks. :) I also tend to average out at my assembler file being about 3 times the size it would be without comments, that seems to be about the right size for me to pick it up in 5 years and still work out what it is doing.

        1. Cheers for that, I didn’t realise that these things had names. It seems that I am a “Whitesmith” user apparently. I don’t think many people are as I get endless stick for coding like that. :)

          1. I am whitesmith as well. Well close to that –
            function sum(item1, item2)
            ..{
            ..result = item1 + item2;
            ..return result;
            ”}

  7. I’ve been employed as a programmer for over 30 years, using various languages, and during that time, I’ve seen my share of indentation wars. It’s hard for me to get too excited listening to someone who claims their style is better than someone else’s. I do believe that you’ve settled upon a style that is as good as it gets. Are there other styles that I would say the same thing about? Yep.

    I think there’s a lot to be said for consistency, and I like the idea of running all code through some sort of prettyprinter to enforce that consistency. A prettyprinter can also point out those inevitable mistakes that sometimes creep in when you thought your code was nested the way it was indented, but in fact there was a subtle typo that caused an easy-to-miss problem in the control structure.

    1. I’d agree. Using indent-mode in Emacs is an example: if you hose something up that indent catches, it will stubbornly refuse to indent code correctly on the following lines. Usually it takes me two or three hits of the tab key before it sinks in that Emacs is trying to tell me something.

  8. I’ve found that it doesn’t really matter what your style guide says, as long as you have _something_ written down. It’s nice to work with code that has a more or less uniform style throughout. I really don’t care if curly braces are behind the if or on their own line: both are perfectly readable, and any developer who whines that one is significantly more readable than the other is just being childish.

    One thing I would say is that in most places I know the 79 (or 80) character limit is a thing of the past. Nobody works on serial terminals with green screens anymore, and as others have said, a character limit often leads to abbreviated names, or weirdly broken up lines.

    As for the whole agile subject: That’s a can of worms, since everybody has their own idea about what Agile is, what is important, and why it does or does not work. I have pretty extensive experience with Scrum, which is a widely used Agile method (although you’re not really supposed to call it a “method”. It’s a “framework”). In any case. I don’t think Scrum is suitable for your purpose, since it depends on having a stable team, and a known availability (available working hours) before you start a sprint (which is what Scrum calls their increment).

    You may have more luck with something like Kanban.

  9. pretty bad C style, there, guys. are you writing in PASCAL? sigh.

    if (a > 1) {
    b = 2;
    } else {
    b = a+1;
    }

    etc.

    concise, does not waste space; and more importantly, works well with emacs built-in c-style formater.

    putting opening braces on a single line is really just for procedure definitions (including main()).

    oh well. it looks like the young guys are ruining the C language….

    (been writing C for a living since the mid 80’s. GOML).

    1. >putting opening braces on a single line is really just for procedure definitions

      I treat code inside curly brackets as a Block and I use exactly the same convention for both which in my case is Allman. A procedure/function simply is a callable Block with a name and definition. In either cases, you can have variable declarations.

      If I want to save space, I put the open bracket on my first line of code instead of having it on its own.

    2. “it looks like the young guys are ruining the C language….

      (been writing C for a living since the mid 80′s. GOML).”
      back in MY DAYS we didn’t need fancy stuff like code highlighting!11einself

  10. Why you no hack in a code formatter into the github? Pull the code every time its updated, run formatting, commit changes with a comment “Formatter Bot Formatting Code”

    I don’t require anybodies code to be formatted in one style or another because if anyone on my team needs to review its a simple alt-shift-F to get it into my format. In fact when reviewing any code the first thing I do is look to see that it compiles then I auto-format to my desired style.

  11. i’d suggest code review. post any changes you made for others to look over and verify (and suggest improvements). Once at least one other person (maybe more, depending on team size) signs off, the code can be checked in.

    reviews can point out minor things like formatting issues or not following code style, or major flaws with the design. It’s really helpful, and is a great sanity check on any code that gets checked in. We use Review Board at work, but I’m sure there are plenty of other tools as well.

  12. Here’s a storey for you!

    I have enlarged knuckles on my hands as a result of the near continuous rapping over the knuckles with a ruler I received in school.

    Dyslexia was unknown at the time and my condition was viewed as behaviour that needed to be corrected.

    Now this group is viewing coding style as a behaviour that needs to be corrected. Very sad.

    Some people have a ‘reason’ for their coding style.

    I code in a style close to whitesmiths style. (for curly bracket languages)

    If I were asked to use a specific style for the use of white space then I would just write a script to convert my code.

    I use variable_name and function_name and CAPITALS are reserved for constants only.

    If I were asked to use camelCase then I would be off the team if I had a choice. Otherwise the rest of the team had better get ready to correct so many errors in my code as a result of camelCase not being compatible with my dyslexia.

    Looking back at what I have just written, I can see that my spell checker is quite happy with variable_name / function_name but has a red line under camelCase. lol

    1. So you think it’s ok for the rest of the team to change their coding style to suit you, but not the other way around? If you are all collaborating on the same code base, let alone the same files, you need to all use the same style. Majority rules except if you are a dictator.

      1. Well it goes like this –

        I have been coding since the late 70’s and I am considered a valuable asset as a coder.

        I don’t expect anybody to be forced into making changes for me. As I mentioned a simple formatter will convert between white space styles. I try as best as I can to compensate for my disability and the fact that I am well regarded indicates that I do this exceedingly well.

        It is more a matter of choice for others. If they choose camelCase than I will try to avoid the project. If I can’t avoid it then others just have to accept how much that slows me down and how many problems it creates along the way.

        To give you an analogy, people don’t seem to mind entering a building on a ramp rather than a small number of steps as the inconvenience is minor. The ramp however is for people in wheelchairs. Taking away the ramp is not problem for most … unless a member of their team is in a wheelchair in which case it becomes a major inconvenience.

        So if you are protesting about the ramp then you are more focussed on your convince rather than the team objective.

      2. @James
        Regardless of what’s “right” or “ok” or “fair” you or he or the team can’t his dyslexia. Either they let him use what style works for him, they deal with a hit to his productivity, or he leaves. There simply aren’t other sensible options, and among those the most sensible is for him to steer his career path toward projects that suit him.

  13. I keep hearing people say that indents cause issues and they need to use spaces instead. However, I have yet to hear anyone who has a good reason for this.

  14. Note that in these religious wars, people always have a *reason* for doing things one way or another. Always use braces even if single-line because it avoids *this* error people sometimes make, always compare the constant with the var if( 4 == i ) instead of the other way around to avoid *that* bug, and so on.

    I’m reminded of Hungarian Notation, which is where you prefix all variable names with information about the type and storage: instead of “Index” you use “iIndex” because it is an integer, “fDistance” for floats, and so on. This led to noisy constructions such as “arru8List” for “array of unsigned 8-bbit integers List” and so on.

    It was started by Charles Simonyi as his graduate thesis, and the intent was to avoid conversion and typing errors: assigning a float to an integer which caused rounding or overflows, for instance, or relying on a stack variable to be static.

    And it *did* work for the purpose. It’s easy to see that assigning fDistance to iFeet might cause integer conversion problems.

    It became widely known because Simonyi got a job as Chief Architect at Microsoft! So he implemented this style in all Microsoft products and it was everywhere! And it was a good thing, wasn’t it? I mean… everyone liked it – didn’t they?

    The point is that simply having a *reason* for choosing a style one way or another isn’t sufficient to make the choice, you also need to attach a *value* to the choice and compare that value with other choices.

    When you don’t do that, you get crazy religious wars where people argue one rationale against another, or Hungarian notation which solves one problem at the expense of a much larger issue. Braces around single-line if’s avoid a certain bug, but the extra whitespace tends to introduce other bugs. You have to compare these two issues and choose the one with better value (ie – fewer bugs), not just say “this rule avoids *tnat* problem”.

    Almost no one has done studies or comparative analysis of the various options. There’s no clear consensus, and no clear evidence either. (The study I cited above is decades old, and may no longer hold true.)

    It is very much a religious war – one person’s unverifiable “proof by story” is contradicted by someone else’s completely different “proof by story”.

    The only way to settle the issue is to do large-sample-space studies. Big corporations such as Google should be doing these types of studies, since the results would increase their coding efficiency.

    But in reality, it’s always “we do it the way the project lead wants it done”.

    Amen

      1. If you accidentally omit one of the equals signs it causes a compiler error. If you do it the other way around no error is detected, it becomes an assignment statement, and the “if” part doesn’t happen.

        It’s an example of “do it this way to avoid *that* type of error”, which works, but as you pointed out it detracts from readability.

        1. Plus: A modern compiler easily generates a warning for the “if(i=4)” case, which will be seen and handled if your policy is to always investigate and solve warnings.

    1. I remember having to sit through a Delphi 1.0 training course with an instructor who insisted on Hungarian notation for every component and variable. Which quickly led to terribly unwieldy and unreadable code after Delphi added all the “glue”. And in 30+ years i’ve never ran into the problem it is supposed to prevent.

  15. Formal SDLCs (software development life cycles) don’t work well on informal FOSS projects such as this because of a couple of reasons. Mainly it is because:

    * There is no client. There is no person for the team to go to to know exactly what is required of the project. So everybody takes on an assumption of what is supposed to be done and then go about doing it at their own time.
    * Teams are typically distributed geographically and accross time zones. SCRUM, a very popular agile method, relies on daily standup meetings where the whole team quickly updates each other on what’s going on. This way problems are nipped in the bud before they become serious. With potentially 12 hours difference between developers this is going to become a problem.

    Agile, XP and all the other types of methodologies are handy when you have to manage risk. The Mooltipass project does not have any risk. Being behind schedule is OK, failed modules needing a rewrite is also OK. The worst that can happen is you can bruise your ego if the project fails. Leave the formal and serious shit to the formal and serious guys, and focus on making a good product :)

    Code review is something else entirely. You must definitely look into that. Do a search for Gerrit. It plugs into Git, and it provides some nice code review capabilities. It is extensively used in the Android project.

    As for coding standards, I don’t feel much for them. I’m very adaptive and I tend to take on the standard that is most natural for the editor that I am using. Don’t waste time enforcing coding standards. Remember, it’s a guideline, not a law. Code review will identify repeat offenders soon enough.

    Take a gander at how the Linux kernel is developed and follow that. It might work. We have mr. Linus himself. King of the castle and lord of all over linuxland. He’s got a group of lieutenants that he trusts completely (his words, not mine). Each lieutenant is responsible for a different aspect of the kernel, such as networking, schedulers, IO etc. Each lieutentant, in turn, has a group of people that he or she trusts. This reversed tree goes on all the way to the bottom, to the small time and casual contributors. This Tree of Trust means that only the good stuff gets to the top. All the crap gets filtered out. Anyone in the world can contribute to the kernel and publish his/her contribution. But to have it accepted into the main Linux repository is another story entirely.

    You most definitely have people on the team that is more experienced in the project and well versed with some or other aspect of it. Make them lieutenants and vote one person as the project owner who has final say. That way pull requests and patches trickle up the tree, and the unwelcome contributions get filtered out along the way.

  16. Real tabs.
    They can be formatted to whatever style anyone wants based on their editor settings, use less disk space than spaces, and wont have problems switching from editor to editor.
    I personally have my editor set to display 8 spaces per tab.

  17. My preference? 1TBS, I guess. But it’s all about preference after all, and anyone who won’t code in whatever style has been decided on for a given collaborative project is just being an ass.

    Spaces over tabs, for sure. All modern editors can interact with spaces as if they were tabs (tab to indent more, shift-tab to indent less, etc.) and tabs require that I reconfigure my editor to the same tab-stop size as the original coder or lots of stuff gets messed up (alignment of comments, for example).

  18. This discussion demonstrates quite well how many different and strongly held opinions there are. The only thing I find works is:
    – Get some opinions
    – Someone in charge make a decision taking these into account. Deciding everything democratically is too disruptive.
    – If it’s not your preferred style just go with it.

    When I’m working on exiting code I just fit in with the existing style. (Hard if there’s already inconsistency though.) Most days I’ll write some Allman code in C# and some Java in the “minor Java K&R variant”. I must admit I was unaware of the official names for these until I saw that Wikipedia page.

  19. Guys, there are code formatters out there since ages. Just use the one that suits your needs and let programmers concentrate to the real work.

  20. Moin,

    I would argue that the actual whitespacing style is of the least possible importance, as long as it’s a style that can easily be configured in any number of widely available automatic formatting tools. In fact, I believe the single most valuable thing you can do to keep a consistent whitespacing style, is to provide prepared configurations for the most used tools: a GNU indent (http://www.gnu.org/software/indent/) command line, Eclipse formatter configuration (Preferences -> C/C++ -> Code Style -> Formatter), and probably vim/emacs configurations (I use neither so I can’t comment).
    Alternatively/additionally you could have a git commit hook to automatically apply your style of choice to all contributions using GNU indent.

    However, whitespacing is only part of a good code style. Other things I try to keep consistent in my code is parameter validation (a check at the beginning of all functions should guard against gross violations of the assumptions the function makes; NULL pointer dereferences should really be a thing of the past), exception handling (I use a linux kernel style “int retval = -1; uint8_t *foo = malloc(10); if(!foo) goto abort; /*…*/ abort: if(foo) free(foo); return retval;” construction in all functions that acquire internal ressources, to make sure that these are freed in any possible execution path) and return value validation.

    Now, as for naming: I personally abhor camelCase becauseItMakesReadingDifficult and leadsToAMentalRollerCoasterWhenTryingToReadStuff. I personally believe it to be the visual equivalent of the arbitrary retarded rollercoaster of U.S. imperial units and the only possible explanation for its prevalence must be some sort of brain malfunction in the original authors of the Java language and the subsequent multiplication of this problem by a another mistake that is the wide adoption of Java as a first programming language in schools and universities.

    Apart from that, naming should follow an internal structure, especially when the code is object oriented (and: most C code is best written in an object oriented way, keeping all related state in one structure, a pointer to which is always passed in the first argument). The naming structure should follow a progression from least specific to most specific part: module-or-functional-group_optional-object_operation. This allows the efficient operation of auto-complete facilities implemented in most modern editors in several workflows of the type “Let’s see, I’m operating with the foo module and have a bar object, what can I do with it?” (type foo_bar_ and let the auto-complete inform you of the availability of the foo foo_bar_new(void), int foo_bar_free(foo), and int foo_bar_frobnicate(foo,int) functions).

    Absolutely banned must be anybody who even hints at the possibility of suggesting to perchance think of maybe using Hungarian notation. It is nearly completely useless in modern toolchains (the editor will readily display all information about a function prototype in both mouseover and auto-complete displays; and the compiler should warn about any mistakes relating to argument or return types) but actively prevents function/variable discovery through auto-complete: you first have to guess the (return) type before you can type at least the first character that will then allow you to use auto-complete.

    And on the subject of the compiler: It’s most often advisable, especially with new codebases, to always compile with -Wall (maybe even -pedantic) and address all issues the compiler complains about right away. You would also use at least –std=c99 because having to place all declarations at the beginning of a function and not allowing “for(int i=0; i<x; i++)" is just downright silly and not conducive to easily read and understood code.


    Henryk Plötz
    Grüße aus Berlin

    1. I agree with everything except the rant on camel case, which was a dramatic departure from the calm, cool, and reasoned approach elsewhere in the post. Personally, I like the more compact variable names that don’t have mindless numbers of underscores. I find they detract from readability. Henryk_finds_this_sentence_easier_to_understand. TheMooltipassDevelopersFoundThisSentenceEasier. But I can do either, and I suspect that most developers can, too, even if they chafe (whine?) because the code standards aren’t their favorites.

  21. We battled for decades to put more stuff on the screen, apparently just so code authors could use extravagant code styles to put less and less on the screen. Spreading code out vertically does not increase readability.

    The code example above, fills half of the screen on my laptop and it barely does anything. A good author can put their entire algorithm on the screen all at once and one can see the whole thing all at once.

    And when the syntax presents you with a perfectly good _ character to separate words with, why not just throw it away and run all the words together? After all let’s be conflicted about our use of space, we have plenty of room to put braces on lines all by themselves but we don’t have room to put _ characters in our variable names.

    coding standards by committee, just love it

    why not just call this project ‘hackaday’s fiero’ and be done with it

    1. >The code example above, fills half of the screen on my laptop

      Buy new laptop, preferably with a screen that has better resolution than THREE YEAR OLD PHONE/10 year old TV….
      Real programmers use 4K monitors nowadays, two of them, or at the very least few FHD with one oriented vertically.

      You are one of those ‘i delete comments to make code more readable’ arduidiot people.

        1. vast majority of consumers are … consumers, not programmers.
          You dont buy F-150 or Silverado (most popular cars in US LOL) to enter in a drifting competition.
          its like logic 101

      1. Not everyone can afford to shell out for the most expensive laptops either. This is especially important to remember on a FOSS project

  22. A shame the various preferred styles can’t be handled by tools. I see how I want in my editor you see how you want in yours. When checked in it is automagically formatted to the project’s official style.

  23. So sad.. i was actually making this exact project.. was getting pretty far and had spent hours on it.

    Now it’s on hackaday.
    Well done i guess.

  24. One reason in favor of camel case is that eclipse recognizes stuff if you just type the capital letters. Ctrl shift t, Ctrl o, Ctrl h, etc. I am not sure it is able to do this for underscores.
    This is an eclipse-only thing but it works similarly in IntelliJ / webstorm. I don’t know about guys using edlin (=vi, emacs).

    I still don’t get the tab vs spaces issue. Just choose one, any editor should easily handle a style. We use a 2 spaces indent converted to tab which is probably hated by both camps here. It’s just what was chosen, nobody complained and nobody has a problem with that.

    The automatic build or push robot can be set to run a cleanup script on the commit and see if the formatting is followed. If not, perhaps it can reject the commit so that the user does not keep committing wrongly formatted code.

  25. UpperCamelCase
    {
    ….lowerCamelCase = 0;
    ….void FunctionCall(foo, argTwo)
    ….{
    ……..if(foo)
    ……..{
    …………Bar(foo);
    ……..}
    ……..else
    ……..{
    …………AnotherFunctionCall(argTwo);
    ……..}
    ….}
    }

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s