-
Notifications
You must be signed in to change notification settings - Fork 18
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Coding guidelines #57
Comments
So, after working a very tiny bit on the #space code-base I also start to feel a need to formalize coding styles. The practical drive here is to minimize size of diffs from pull requests. If everyone uses different editor settings the code is going to be constantly re-formatted back and forth by different people. Now, IMO, all those standardization efforts can succeed only if those are enforced automatically as part of the build. Non-conforming code should simply break a build. Keeping the above in mind I would propose to introduce https://github.com/mdevils/node-jscs checks which is like jshint pushed a bit further. If we consider going down this path we should do it rather sooner than later as a bigger code-base will make it harder / impossible. BTW, those checks can be introduced on the folder-per-folder basis so there is a way of progressively introducing things. WDYT? |
For code formatting, we could use grunt-jsbeautifier to format js code, as it is done in noder-js, see here. |
Definitively needed! |
We´ll as I brought up the issue I +1 these efforts. But I would also suggest that a general style guide is used/defined which everyone adheres to while writing the code. This minimizes the effort to "fix"/normalize it afterwards. Most of it is just a matter of personal discipline, which of course can and should be aided by tools. But in general it would be better not to have the different styles in the beginning. To cite your aria templates contribution guidelines:
|
Talking about the code style: If the rules are imposed by the automatic tools (jshint, style checkers/formatters), you'll learn the rules pretty quickly. In my experience, it's waaay better to have a build-time rejections than any written guidelines because people don't read and/or forget the latter. One little remark regarding grunt-jsbeautifier |
How about a pull request first - before forking? |
Personally I prefer having a formal reference for coding style. Something easier to understand than a configuration file of a (often not exhaustive) formatting tool. |
@ymeine IMHO is something is not enforced automatically it will be neglected and not followed. Having formal / written guidelines are good (and I'm sure we can generate human readable description from a config file, if needed!) but if violations don't break the build we are going to catch some of those violations during code review and some others will be left unnoticed. I really would like to automate all the things we can - I simply don't want to think about those rules while coding / doing code reviews. |
On attester, we have a grunt task (not automatic, manual so far) that formats the code and launches jshint [1]. To get some insight about how this works, you can
It's as simple as that and you don't need a verbose document ;) Do this a few times and you'll learn the rules without reading anything. IMO what we should rather discuss is what to choose :)
[1] https://github.com/attester/attester/blob/master/Gruntfile.js#L55 |
@PK1A Sorry, I forgot to precise that I prefer having that too! 😄 Of course I'm in favor of automation, and +1 for generating something from a config file! However I think that a classical documentation format for coding style (in addition to the rest) allows talking about traits that go beyond what is covered by the tools we could use. Coding is not just a matter of syntax and indentation. Well, personally I follow guidelines if I know there are some and where to find them... but I can't say it would be the case of everyone 😛 |
@ymeine cool, looks like we are on the same page then 👍 |
So what is the status on this matter now? |
From what I gather we'll:
|
In terms of written coding guidelines, I found these ones to be really good to me Have a look at it, it is huge, but every single usecase is illustrated with a example of bad/good snippet |
@dpreussner yes, I'm starting experimenting with https://github.com/mdevils/node-jscs |
Here is more info on jscs: https://yannick.cr/posts/enforcing-coding-rules-in-your-team-with-jscs/post |
BTW apart from JSCS we can also add an http://editorconfig.org/ is a project that aims to provide a simple configuration file which will be then read by a plugin for you IDE, which in turn transparently enforces the tabs vs spaces, trailing whitespace and all those kinds of conventions. It seems there are plugins for everything except Eclipse :) |
@jakub-g Sounds like a neat idea. What is the general status regarding the coding conventions? I think the project is past the "adjust manually" phase... |
This issue has been created after a post from @dpreussner on the at.com forum.
Since the code base is still at an early stage, we should take the opportunity to lay out a set of basic rules to follow so that code style stay consistent everywhere.
These rules could be listed in the (to be created) Contributing.md file.
The text was updated successfully, but these errors were encountered: