{"id":23291008,"url":"https://github.com/jplusplus/styleguide","last_synced_at":"2025-07-11T12:44:29.036Z","repository":{"id":6367966,"uuid":"7605298","full_name":"jplusplus/styleguide","owner":"jplusplus","description":"This styleguide explains how developers at Journalism++ write. It contains precise stylistic rules as well as overarching principles that Journalism++ pushes for.","archived":false,"fork":false,"pushed_at":"2014-01-06T10:37:17.000Z","size":114,"stargazers_count":12,"open_issues_count":0,"forks_count":1,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-04-14T04:55:29.070Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/jplusplus/styleguide","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jplusplus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-01-14T14:05:02.000Z","updated_at":"2017-05-05T07:37:33.000Z","dependencies_parsed_at":"2022-09-24T02:01:58.711Z","dependency_job_id":null,"html_url":"https://github.com/jplusplus/styleguide","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jplusplus/styleguide","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jplusplus%2Fstyleguide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jplusplus%2Fstyleguide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jplusplus%2Fstyleguide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jplusplus%2Fstyleguide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jplusplus","download_url":"https://codeload.github.com/jplusplus/styleguide/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jplusplus%2Fstyleguide/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264811587,"owners_count":23667783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-20T05:13:51.429Z","updated_at":"2025-07-11T12:44:28.996Z","avatar_url":"https://github.com/jplusplus.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Best practices and coding rules\n\nThis guide aims to define the rules and good practices of programming within\nJournalism++ projects. The content of this guide is under MIT licence.\n\n## \u003ca name='TOC'\u003eTable of Contents\u003c/a\u003e\n  1. [Projects installation](#installation)\n    2. [README](#readme)\n    2. [Makefile](#makefile)\n    2. [Configuration files](#configuration)\n    2. [Dependencies](#dependencies)\n  1. [Comments](#comments)\n    2. [Be a storyteller](#storyteller)\n    2. [Every developer is different](#different)\n  1. [Text editor](#editor)\n  1. [Languages](#languages)\n    2. [Javascript](#javascript)\n  1. [Issues : The boy who cried Wolf](#issues)\n\n\n```                               \n          .=.,   \n         ;c =\\   /_ Comment is free, but indents are sacred.\n       __|  _/     \n     .'-'-._/-'-._\n    /..   ____    \\\n   /' _  [\u003c_-\u003e] )  \\\n  (  / \\--\\_\u003e/-/'._ )\n   \\-;_/\\__;__/ _/ _/\n    '._}|==o==\\{_\\/\n     /  /-._.--\\  \\_\n    // /   /|   \\ \\ \\\n   / | |   | \\;  |  \\ \\\n  / /  | :/   \\: \\   \\_\\\n /  |  /.'|   /: |    \\ \\\n |  |  |--| . |--|     \\_\\\n / _/   \\ | : | /___--._) \\\n|_(---'-| \u003e-'-| |       '-'\n      /_/     \\_\\\n```\n\n## \u003ca name='installation'\u003eProjects installation\u003c/a\u003e\n\nYou must always work under the assumption that your project will be open\nsource. The difference between a good programmer and bad programmer coming\nfrom its capacity to work in a network. Your code must be addressed to the\ncommunity, systematically.\n\n### \u003ca name='readme'\u003eREADME\u003c/a\u003e\n\nEvery new projet **starts by the creation of a README file**. This file\ndetails at least :\n\n  - Installation process : any new developer should be able to install the project from scratch;\n  - required environments variables;\n  - required programmes and dependencies;\n  - licence of the project.\n\n### \u003ca name='makefile'\u003eMakefile\u003c/a\u003e\n\nIt's a good idea to put in a __Makefle__ the scripts needed to manage the project. \n\n  - Install the project (download dependancies, build binaries, setup databases);\n  - Run the project (launch databases, web application, job runners). Take a look to [Foreman](https://github.com/ddollar/foreman) to do that;\n  - Run the unit tests;\n  - Package the project for delivery.\n\nFor 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)\n\n### \u003ca name='configuration'\u003eConfiguration files\u003c/a\u003e\n\nMost modern languages offer tools to manage different configuration files. Pay\nattention to :\n\n  - Split information that allow the programme to work from the credential values (such as authentication key, etc);\n  - **place systematically files containing passwords into .gitignore** to avoid to communicate those to malicious people;\n  - create templates files for these \"ghost files\".\n\n### \u003ca name='dependencies'\u003eDependencies\u003c/a\u003e\n\nPython and NodeJS both use very smart package managers. With smart tools,\nsmart practices come along :\n\n  - Detail every dependencies into a file that your package manager can read (Pip, NPM, etc);\n  - give the highest priority to the last version of a dependence;\n  - never, ever, use a deprecated or poorly documented dependency;\n  - 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\").\n\n## \u003ca name='comments'\u003eComments\u003c/a\u003e\n\n### \u003ca name='storyteller'\u003eBe a storyteller\u003c/a\u003e\n\nA beautiful algorithm is designed like a beautiful story. Unfortunately, it's\nnot always easy to distinguish every key events in a story, and it's even more\ncomplicated when this story is written with code. Do not be just a good\nauthor, be also a good storyteller.\n\n### \u003ca name='different'\u003eEvery developer is different\u003c/a\u003e\n\nNever forget that the developers won't be necessary at the same level of\nknowledge than you:\n\n  - Take the time to explain your choices; \n  - make sure to explain clearly when you use complex expressions;\n  - insert links to documentation or Stack Overflow when you solve a problem that troubled you for hours.\n\n## \u003ca name='editor'\u003eText editor\u003c/a\u003e\n\nWe are not offended if your prefer TextMate or Netbeans rather than the great\nand unrivaled **Sublime Text 2**. Most important is that your project can be\nopened with any text editor which is not yours and without prior configuration\n(so most IDEs are out of the table).\n\n  \nFrom now, configure your editor to:\n\n  - Use soft-tabs and spaces indentation (never mix up spaces and tabulations);\n  - [Tabs are evil](http://www.emacswiki.org/emacs/TabsAreEvil);\n  - always save in UTF-8;\n  - use UNIX line endings;\n  - give priority to middlewares rather than executable pre-processors to compile your assets (like Less, SCSS, minfiiers, etc).\n  - add two rulers to your editor. The first at 80 characters: try not to exceed it. The second at 100 characters: **never exceed it**.\n\n## \u003ca name='languages'\u003eLanguages\u003c/a\u003e\n\n### \u003ca name='javascript'\u003eJavascript\u003c/a\u003e\n\nJavascript just got out of a long and painful teenage angst. It is today at a\ncertain level of maturity that the good practices of programming maintain. To\navoid going backward, we have to be very rigorous with Javascript. The\nlanguage's permissiveness will not force you to do so, so you'll have to apply\nyourself.\n\nFor theses reasons we encourage you to follow the comprehensive [Javascript\nStyle Guide](https://github.com/airbnb/javascript) provided by Airbnb.\n\n## \u003ca name='issues'\u003eIssues : The boy who cried Wolf\u003c/a\u003e\n\nDo you know the fable of [The Boy Who Cried Wolf](https://en.wikipedia.org/wik\ni/The_Boy_Who_Cried_Wolf) ? It's about a little boy who\namuses himself by crying \"wolf\" in order to see the panic he causes in its\nvillage, but consequently does not get help when a real wolf appears and eats\nhalf of a flock of sheep.\n\nDo not cry wolf too if you want to see the true issues solved. You may also\nfollow the excellent [Issues Guidelines](https://github.com/necolas/issue-guidelines) \nby Nicolas Gallagher.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjplusplus%2Fstyleguide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjplusplus%2Fstyleguide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjplusplus%2Fstyleguide/lists"}