Feature - 2910 Add coding guidelines #559

Poltergeist · 2016-01-19T10:37:00Z

For now these rules are open for discussion.

This PR introduces new eslint settings which are only warnings for now until all issues are resolved then these warnings are switched to errors.

This closes mesosphere/marathon#2910

pierluigi · 2016-01-19T10:39:10Z

coding-guidelines/coding-guidelines.md

+Rules:
+- Indentation is done with 2 spaces in most cases.
+- Line breaks are only done if needed, try to use the 80 character limit.
+- Strings are splitted at the latest possible position.


pierluigi · 2016-01-19T11:07:39Z

@Poltergeist Thanks a ton for taking care of this. Really appreciated.

aldipower · 2016-01-19T11:09:04Z

coding-guidelines/coding-guidelines.md

+## JSDoc
+If there is a return there should be a type and description.
+If there is one or multiple parameter/s there should be a name, type and description for each one.
+


I would add, that the function should be understandable without commenting, so it actually needs no comment header. A function should be descriptive by reading the code or the function definition itself.

If the code itself needs commenting then you probably did something wrong.

I would compare the JSDoc description to a cover text of a book you should not need to read it to understand the contents but if you scan it you know something about the contents before reading it.

Think about the function-naming and the parameters as the cover text. :)

What I find useful is to document a whole file with a meaningful description on the top, but not single functions.

aldipower · 2016-01-19T11:23:55Z

This is already very complete! Great! Good work so far. The really important things are all covered. It's a good doc that can be complemented later, if needed.

Some things I think about, that should be documented, are:

let in and after block-scopes.
In general we prefer a more functional coding style. .forEach() preferred instead of a for-loop.
If you don't know how to style the code and can't find it here, look at the AirBnB styles. A lot is derived from there!
Functions and code must be self-descriptive. Use function doc-headers only if really necessary.
Usage of template-strings
CSS coding styles
Sort alphabetically
How to indent chained functions like promises or map/reduce-functions.
Use named function if they are in "private" scope.

aldipower · 2016-01-19T13:47:35Z

coding-guidelines/coding-guidelines.md

+  - Indentation is 2 spaces.
+  - No multiple empty lines.
+
+We prefer a functional approach and try to use the abstractions over


Sounds perfect to me. Thanx!

Minor:
try to use the_se_ abstractions

aldipower · 2016-01-19T14:21:15Z

coding-guidelines/coding-guidelines.md

+```
+
+## JSDoc
+JSDoc blocks should be avoided in favor to code descriptiveness. If the are necessary these rules apply:


👍
Little typo (maybe mine ;) ):
If the_y_

Remove typos Remove uneccessary examples add new examples

This change is so that the build does not break until all new rules are refactored

aldipower · 2016-01-21T10:38:20Z

Let's merge this! :)

This was a lot of work @Poltergeist , good job, thanx!

Most things are covered!
The guideline can/should be extended/complemented at every time.

Feature - 2910 Add coding guidelines

Poltergeist added the in progress label Jan 19, 2016

pierluigi reviewed Jan 19, 2016
View reviewed changes

aldipower reviewed Jan 19, 2016
View reviewed changes

Poltergeist force-pushed the feature/add-coding-guidelines branch from c8efae6 to 586bc57 Compare January 19, 2016 13:34

aldipower reviewed Jan 19, 2016
View reviewed changes

Poltergeist force-pushed the feature/add-coding-guidelines branch from 358f0f7 to 0ff251d Compare January 19, 2016 16:02

Philipp Hinrichsen added 17 commits January 20, 2016 14:22

Add coding guidelines with some complex examples

0f2a2d7

Add one-var enforce rule to eslint config file

83cce54

Add the block-spacing rule to the eslint config

372e021

Add suggestions to the document

19e7026

Remove typos Remove uneccessary examples add new examples

Add general info section at the top

b4237dd

Change new eslint settings to warnings

723e4a4

This change is so that the build does not break until all new rules are refactored

Change General from topic to subtopic

ea50924

Change the order of the topics

53f7509

Remove eslint example file

8388c66

Fix typos, add title case to all headlines

d81c7f4

Change string to object

6985906

Add semicolon warnings

125cb44

Add semicolon to the examples

36df12d

Fix the wording of the JSDoc section

0bda9aa

Fix example to be valid code.

29dd46f

Fix typos

f2527a5

Add ternaries section

d96f2ff

Poltergeist force-pushed the feature/add-coding-guidelines branch from 3d6bbea to d96f2ff Compare January 20, 2016 13:22

Change line breaks in an argument list.

ecc4e39

Poltergeist changed the title ~~[WIP] Feature - 2910 Add coding guidelines~~ Feature - 2910 Add coding guidelines Jan 20, 2016

Move coding-guidelines to root directory

bfd5b55

Poltergeist assigned aldipower Jan 21, 2016

aldipower added a commit that referenced this pull request Jan 21, 2016

Merge pull request #559 from mesosphere/feature/add-coding-guidelines

6562872

Feature - 2910 Add coding guidelines

aldipower merged commit 6562872 into master Jan 21, 2016

aldipower deleted the feature/add-coding-guidelines branch January 21, 2016 10:38

aldipower removed the in progress label Jan 21, 2016

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feature - 2910 Add coding guidelines #559

Feature - 2910 Add coding guidelines #559

Poltergeist commented Jan 19, 2016

pierluigi Jan 19, 2016

pierluigi commented Jan 19, 2016

aldipower Jan 19, 2016

aldipower Jan 19, 2016

Poltergeist Jan 19, 2016

aldipower Jan 19, 2016

aldipower Jan 19, 2016

aldipower commented Jan 19, 2016

aldipower Jan 19, 2016

aldipower Jan 19, 2016

aldipower Jan 19, 2016

aldipower commented Jan 21, 2016

Feature - 2910 Add coding guidelines #559

Feature - 2910 Add coding guidelines #559

Conversation

Poltergeist commented Jan 19, 2016

Choose a reason for hiding this comment

pierluigi commented Jan 19, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aldipower commented Jan 19, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aldipower commented Jan 21, 2016