Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/jplusplus/styleguide

This styleguide explains how developers at Journalism++ write. It contains precise stylistic rules as well as overarching principles that Journalism++ pushes for.
https://github.com/jplusplus/styleguide

Last synced: 12 months ago
JSON representation

This styleguide explains how developers at Journalism++ write. It contains precise stylistic rules as well as overarching principles that Journalism++ pushes for.

Awesome Lists containing this project

README 

          
# Best practices and coding rules



This guide aims to define the rules and good practices of programming within

Journalism++ projects. The content of this guide is under MIT licence.



## Table of Contents

  1. [Projects installation](#installation)

    2. [README](#readme)

    2. [Makefile](#makefile)

    2. [Configuration files](#configuration)

    2. [Dependencies](#dependencies)

  1. [Comments](#comments)

    2. [Be a storyteller](#storyteller)

    2. [Every developer is different](#different)

  1. [Text editor](#editor)

  1. [Languages](#languages)

    2. [Javascript](#javascript)

  1. [Issues : The boy who cried Wolf](#issues)



```                               

          .=.,   

         ;c =\   /_ Comment is free, but indents are sacred.

       __|  _/     

     .'-'-._/-'-._

    /..   ____    \

   /' _  [<_->] )  \

  (  / \--\_>/-/'._ )

   \-;_/\__;__/ _/ _/

    '._}|==o==\{_\/

     /  /-._.--\  \_

    // /   /|   \ \ \

   / | |   | \;  |  \ \

  / /  | :/   \: \   \_\

 /  |  /.'|   /: |    \ \

 |  |  |--| . |--|     \_\

 / _/   \ | : | /___--._) \

|_(---'-| >-'-| |       '-'

      /_/     \_\

```



## Projects installation



You must always work under the assumption that your project will be open

source. The difference between a good programmer and bad programmer coming

from its capacity to work in a network. Your code must be addressed to the

community, systematically.



### README



Every new projet **starts by the creation of a README file**. This file

details at least :



  - Installation process : any new developer should be able to install the project from scratch;

  - required environments variables;

  - required programmes and dependencies;

  - licence of the project.



### Makefile



It's a good idea to put in a __Makefle__ the scripts needed to manage the project. 



  - Install the project (download dependancies, build binaries, setup databases);

  - Run the project (launch databases, web application, job runners). Take a look to [Foreman](https://github.com/ddollar/foreman) to do that;

  - Run the unit tests;

  - Package the project for delivery.



For speficic use, like deployement which depends of your needs, it's better to put these in a non-shared script file, like a [Fabfile](http://docs.fabfile.org)



### Configuration files



Most modern languages offer tools to manage different configuration files. Pay

attention to :



  - Split information that allow the programme to work from the credential values (such as authentication key, etc);

  - **place systematically files containing passwords into .gitignore** to avoid to communicate those to malicious people;

  - create templates files for these "ghost files".



### Dependencies



Python and NodeJS both use very smart package managers. With smart tools,

smart practices come along :



  - Detail every dependencies into a file that your package manager can read (Pip, NPM, etc);

  - give the highest priority to the last version of a dependence;

  - never, ever, use a deprecated or poorly documented dependency;

  - if you are not sure to be able to maintain the project, use fixed version numbers rather than aliases to the last versions (Good : "2.0.1", Bad : "latest").



## Comments



### Be a storyteller



A beautiful algorithm is designed like a beautiful story. Unfortunately, it's

not always easy to distinguish every key events in a story, and it's even more

complicated when this story is written with code. Do not be just a good

author, be also a good storyteller.



### Every developer is different



Never forget that the developers won't be necessary at the same level of

knowledge than you:



  - Take the time to explain your choices; 

  - make sure to explain clearly when you use complex expressions;

  - insert links to documentation or Stack Overflow when you solve a problem that troubled you for hours.



## Text editor



We are not offended if your prefer TextMate or Netbeans rather than the great

and unrivaled **Sublime Text 2**. Most important is that your project can be

opened with any text editor which is not yours and without prior configuration

(so most IDEs are out of the table).



  

From now, configure your editor to:



  - Use soft-tabs and spaces indentation (never mix up spaces and tabulations);

  - [Tabs are evil](http://www.emacswiki.org/emacs/TabsAreEvil);

  - always save in UTF-8;

  - use UNIX line endings;

  - give priority to middlewares rather than executable pre-processors to compile your assets (like Less, SCSS, minfiiers, etc).

  - add two rulers to your editor. The first at 80 characters: try not to exceed it. The second at 100 characters: **never exceed it**.



## Languages



### Javascript



Javascript just got out of a long and painful teenage angst. It is today at a

certain level of maturity that the good practices of programming maintain. To

avoid going backward, we have to be very rigorous with Javascript. The

language's permissiveness will not force you to do so, so you'll have to apply

yourself.



For theses reasons we encourage you to follow the comprehensive [Javascript

Style Guide](https://github.com/airbnb/javascript) provided by Airbnb.



## Issues : The boy who cried Wolf



Do you know the fable of [The Boy Who Cried Wolf](https://en.wikipedia.org/wik

i/The_Boy_Who_Cried_Wolf) ? It's about a little boy who

amuses himself by crying "wolf" in order to see the panic he causes in its

village, but consequently does not get help when a real wolf appears and eats

half of a flock of sheep.



Do not cry wolf too if you want to see the true issues solved. You may also

follow the excellent [Issues Guidelines](https://github.com/necolas/issue-guidelines) 

by Nicolas Gallagher.