https://github.com/jwilk/coding-guidelines

Jakub's coding guidelines (and release checklist)
https://github.com/jwilk/coding-guidelines

Last synced: about 1 month ago
JSON representation

Jakub's coding guidelines (and release checklist)

• Host: GitHub
• URL: https://github.com/jwilk/coding-guidelines
• Owner: jwilk
• Created: 2017-04-01T13:57:49.000Z (over 7 years ago)
• Default Branch: master
• Last Pushed: 2024-01-29T10:51:17.000Z (11 months ago)
• Last Synced: 2024-08-09T00:22:29.509Z (5 months ago)
• Language: reStructuredText
• Size: 35.2 KB
• Stars: 2
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README

Awesome Lists containing this project

README

        
Documentation

=============

* Avoid ``.rst`` extensions for files designed to be read directly

  (such as ``README.rst``).

  If the file declares file format in the vim modeline (e.g. ``vim:ft=rst``),

  GitHub no longer requires the extension to render the file correctly.

* Avoid ``.txt`` extensions for files designed to be read directly.

* ``doc/README`` should briefly describe the project.

* There should be ``README`` → ``doc/README`` symlink.

* The ``README`` symlink should not shipped in release tarballs.

* Validate reStructuredText documents with ``rst2xml --strict``.

* Validate POD documents with ``podchecker``.

* DocBook XML documents should be avoided.

* Validate legacy DocBook XML documents with ``xmllint --valid``.

* Check URLs using urlycue_.

* Check that version numbers in documentation and in the code match.

* Manual pages should include version numbers.

* Manual page dates should be up-to-date.

* English manual page dates should be in the *YYYY*-*MM*-*DD* format.

  Manual pages must not use a middle-endian date format.

* In manual pages:

  * apostrophes should be written as ``'``, not ``\(aq``;

  * hyphens should be written as ``-``;

  * minus-signs should be written as ``\-``.

* ``rst2man`` calls should use ``--input-encoding=UTF-8``.

* Built manual pages should not include vim modelines.

* Check that the changelog is complete.

.. _urlycue:

   https://jwilk.net/software/urlycue

Copyright

=========

* In repo, there should be top-level ``LICENSE`` (or ``COPYING``) file.

* In release tarballs, ``LICENSE`` (or ``COPYING``)

  should be moved to the ``doc`` subdirectory.

* Copyright notices should be up-to-date.

* GPLv2 files should carry the following license notice:

   This file is part of *PROJECT*.

   *PROJECT* is free software; you can redistribute it and/or modify it under

   the terms of the GNU General Public License version 2 as published by the

   Free Software Foundation.

   *PROJECT* is distributed in the hope that it will be useful, but WITHOUT ANY

   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS

   FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more

   details.

Spelling

========

* Check spelling with mwic_.

* Check spelling with anorack_.

.. _mwic:

   https://jwilk.net/software/mwic

.. _anorack:

   https://jwilk.net/software/anorack

Build system

============

* Autoconf-based packages should provide the ``private/autogen`` and

  ``private/autoclean`` scripts.

* The name of Autoconf configuration header files should be ``autoconf.h``

  (or similar).

* ``autoconf`` should fail when 3rd-party macros are missing, e.g.::

   m4_pattern_forbid(

       [^PKG_CHECK_MODULES],

       [undefined macro PKG_CHECK_MODULES; install pkg-config and run private/autogen]

   )

* Check if all the files (binaries, manual pages) are installed correctly.

Portability

===========

* Use ``perl -pi`` (rather than ``sed -i``) for in-place edits.

* Don't assume ``install`` is GNU install.

  Don't use ``install -D`` because GNU install does something entirely different

  that FreeBSD install.

* Makefiles can require GNU make,

  but then they should fail with helpful error when run against BSD make.

Python code

===========

* Check Python code with pydiatra_.

* Check Python code with pyflakes_.

* Check Python code with pylint_.

* Python modules should have sensible ``__all__``.

* Validate module long description with ``rst2xml --strict``.

* Don't assume that the Python interpreter is at ``/usr/bin/python``.

* ``setup.py`` should not import any code from the source tree.

* Check Python version at runtime.

* Check Python version at install time.

* Byte-compile source at install time.

.. _pydiatra:

   https://jwilk.net/software/pydiatra

.. _pyflakes:

   https://github.com/PyCQA/pyflakes

.. _pylint:

   https://github.com/PyCQA/pylint

Perl code

=========

* Check Perl code with perlcritic_.

* Every Perl script should start with ``no lib '.';``

  as a defence against CVE-2016-1238.

* Don't assume that the Perl interpreter is at ``/usr/bin/perl``.

.. _perlcritic:

   https://metacpan.org/dist/Perl-Critic

Shell scripts

=============

* Check shell scripts with shellcheck_.

* Shell scripts should use ``set -e``.

* Shell scripts should use ``set -u``.

* Use ``command -v``, not ``which``.

.. _shellcheck:

   https://www.shellcheck.net/

C code

======

* LFS build flags should be enabled.

* Environment variables such as ``CC``, ``CFLAGS``, etc. should be honored.

* ``CFLAGS`` should be honored when linking

  (so that ``-fsanitize=address`` etc. work).

* Check code with cppcheck_.

* Use ``tiparm()`` instead of ``tparm()``.

.. _cppcheck:

   https://cppcheck.sourceforge.io/

CLI

===

* The ``--version`` option should print to stdout, not stderr.

  Note that in Python prior to 3.4,

  ``argparse`` doesn't do it correctly out of the box:

  https://bugs.python.org/issue18920

* The ``--version`` option should print versions of most important underlying

  libraries.

* Exit status for ``--version`` should be 0.

* The ``--help`` option should print to stdout, not stderr.

* Exit status for ``--help`` should be 0.

* Programs that produce copious amount of output (and do nothing else besides

  that) should have default signal handler for ``SIGPIPE``.

* Programs should catch exceptions that could be caused by typical user or

  environment errors (e.g., a file cannot be opened).

  There should be command-line option to let these exceptions go through.

Tests

=====

* Coverage file should be up to date.

* There should be an easy way to run the tests against installed package.

Release tarballs

================

* Files should have sane ownership (``root:root``)

  and permissions (0644 or 0755).

* Directory entries should be sorted.

  (For GNU tar, use ``--sort=name``.)

* The POSIX 1003.1-1988 (ustar) format should be used.

* Tarballs should be compressed with ``gzip -9n``.

* XZ compression can be used if it would save at least 64 KiB.

* For XZ compression, the least memory-intensive preset that still offers

  optimal file size should be used. The ``-e`` option should be used.

VCS

===

* Most items in ``.gitignore`` and ``.gitattributes``

  should be anchored with ``/``.

Continuous integration

======================

* When possible, the above checks should be automated using CI.

.. vim:ft=rst ts=3 sts=3 sw=3 et