{"action":"created","issue":{"url":"https://api.github.com/repos/keyboardio/Kaleidoscope/issues/134","repository_url":"https://api.github.com/repos/keyboardio/Kaleidoscope","labels_url":"https://api.github.com/repos/keyboardio/Kaleidoscope/issues/134/labels{/name}","comments_url":"https://api.github.com/repos/keyboardio/Kaleidoscope/issues/134/comments","events_url":"https://api.github.com/repos/keyboardio/Kaleidoscope/issues/134/events","html_url":"https://github.com/keyboardio/Kaleidoscope/issues/134","id":233089245,"number":134,"title":"Coding Style Guidelines","user":{"login":"algernon","id":17243,"avatar_url":"https://avatars0.githubusercontent.com/u/17243?v=3","gravatar_id":"","url":"https://api.github.com/users/algernon","html_url":"https://github.com/algernon","followers_url":"https://api.github.com/users/algernon/followers","following_url":"https://api.github.com/users/algernon/following{/other_user}","gists_url":"https://api.github.com/users/algernon/gists{/gist_id}","starred_url":"https://api.github.com/users/algernon/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/algernon/subscriptions","organizations_url":"https://api.github.com/users/algernon/orgs","repos_url":"https://api.github.com/users/algernon/repos","events_url":"https://api.github.com/users/algernon/events{/privacy}","received_events_url":"https://api.github.com/users/algernon/received_events","type":"User","site_admin":false},"labels":[{"id":63830151,"url":"https://api.github.com/repos/keyboardio/Kaleidoscope/labels/enhancement","name":"enhancement","color":"84b6eb","default":true}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":0,"created_at":"2017-06-02T06:32:18Z","updated_at":"2017-06-02T07:10:12Z","closed_at":null,"body":"@obra mentioned on IRC the other day that Kaleidoscope could really use a coding style guide. Though some of it is enforced now via `make astyle`, that's mostly whitespace, and formatting. Naming, code organization, and similar things are not covered, and there are a number of different styles used throughout the codebase.\r\n\r\nIt would be incredibly useful not only for future authors, but for bringing the current set of plugins to a common ground, too.\r\n\r\n(I'm going through a number of existing guides, and will share my opinion in followup comments)"},"comment":{"url":"https://api.github.com/repos/keyboardio/Kaleidoscope/issues/comments/305708196","html_url":"https://github.com/keyboardio/Kaleidoscope/issues/134#issuecomment-305708196","issue_url":"https://api.github.com/repos/keyboardio/Kaleidoscope/issues/134","id":305708196,"user":{"login":"algernon","id":17243,"avatar_url":"https://avatars0.githubusercontent.com/u/17243?v=3","gravatar_id":"","url":"https://api.github.com/users/algernon","html_url":"https://github.com/algernon","followers_url":"https://api.github.com/users/algernon/followers","following_url":"https://api.github.com/users/algernon/following{/other_user}","gists_url":"https://api.github.com/users/algernon/gists{/gist_id}","starred_url":"https://api.github.com/users/algernon/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/algernon/subscriptions","organizations_url":"https://api.github.com/users/algernon/orgs","repos_url":"https://api.github.com/users/algernon/repos","events_url":"https://api.github.com/users/algernon/events{/privacy}","received_events_url":"https://api.github.com/users/algernon/received_events","type":"User","site_admin":false},"created_at":"2017-06-02T07:10:12Z","updated_at":"2017-06-02T07:10:12Z","body":"# [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html)\r\n\r\nOne of the selling points of this guide is that we use the formatting anyway, and it is a thorough guide, covering pretty much all aspects of the code. However, it has a number of issues too, which prevents us from using it as-is.\r\n\r\nFirst of all, it is written with traditional x86-64 libraries and applications in mind, where you control the build system, and so on. This can be easily seen when it talks about [names and order of includes](https://google.github.io/styleguide/cppguide.html#Names_and_Order_of_Includes). We can't name our things like that, because of limitation of the Arduino build system: we can't use `#include <Kaleidoscope/LED/Theme/Something.h>`, or `#include <Kaleidoscope/OneShot.h>`, because Arduino won't find the libraries then. We may be able to build a tool on top of it that would, but then we'd lose the ability to use the Arduino IDE.\r\n\r\nThe guide discourages static members too (though allows them), along with globals - while we build heavily on those to conserve space, to be friendlier to the end-user, among other things.\r\n\r\nThe aim of Google's style guide is to make the code better organized, and more understandable for other developers. Our aim is to make the code easier to use for the novice user, for whom their firmware may be the first program they ever create.\r\n\r\n## Existing differences\r\n\r\nThe list below is a collection of issues where our code differs from the recommendation, and where adapting to the guide is not immediately an obvious win. There are other cases where our code differs which I don't list, when adapting to the guide is a no-brainer.\r\n\r\n* The guide mandates [lowercase namespace names](https://google.github.io/styleguide/cppguide.html#Namespace_Names), while we (my plugins, mostly) use CamelCase. Lowercase makes sense, making it clear that a namespace is not a class, though.\r\n* We use `#pragma once` instead of [`#define` guards](https://google.github.io/styleguide/cppguide.html#The__define_Guard), but that accomplishes the same thing. Nevertheless, we should use one or the other, so we'd either have to switch, or augment the guide with a note.\r\n* We use preprocessor macros a lot, while the guide [discourages them](https://google.github.io/styleguide/cppguide.html#Preprocessor_Macros).\r\n* We use plenty of non-standard language extensions, while the guide [does not allow them](https://google.github.io/styleguide/cppguide.html#Nonstandard_Extensions). We don't need to care much about portability, because we'll be using GCC anyway. (Or perhaps Clang, which pretty much supports all the same extensions, as far as we are concerned)\r\n* Our naming rules differ: the guide [suggests](https://google.github.io/styleguide/cppguide.html#General_Naming_Rules) snake_case for variables, for example. It also uses [lowercase names for files](https://google.github.io/styleguide/cppguide.html#File_Names). These all stem from the same goal of not using CamelCase by default, it seems. Mind you, reserving CamelCase for classes, and snake_case for variables is not a terrible idea... It does go against Arduino practices as far as I see, though.\r\n\r\n## Summary\r\n\r\nThere are differences between the usual Arduino way, and between Google's guide, but not too much. It feels like we could opt for following Google's guide, with a few exceptions added to cover our use-cases."}}
{"actor":{"display_login":"algernon"}}