Guidelines for GtkSourceView

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

GtkSourceView source code is maintained using the git version control system

and is available at the following location:

    git://git.gnome.org/gtksourceview

Or if you have an account on GNOME servers:

    ssh://USERNAME@git.gnome.org/git/gtksourceview

A web interface is available at:

    https://git.gnome.org/browse/gtksourceview/

Please don't commit directly to the git repository unless

you have been given the green light to commit freely to GtkSourceView.

When in doubt assume you haven't ;-).

Please attach patches in bugzilla (http://bugzilla.gnome.org).

If the patch fixes a bug that is not reported yet in bugzilla or is

an enhancement, create a new bugreport.

Please create patches with the git format-patch command.

If you are a translator feel free to mark strings for translation,

fix typos in the code, etc.

Please send patches for build & configure fixes too.  I really appreciate

your help, I just want to review these fixes before applying.

If you are a "build sheriff", feel free to commit fixes for build and

configure.

When committing to the GtkSourceView git repository make sure to include a

meaningful commit message. Changes without a sufficient commit message

will be reverted. Commit messages should have the following format:

=== begin example commit ===

Short explanation of the commit

Longer explanation explaining exactly what's changed, whether any

external or private interfaces changed, what bugs were fixed (with bug

tracker reference if applicable) and so forth. Be concise but not too brief.

=== end example commit ===

  - Always add a brief description of the commit to the _first_ line of

    the commit and terminate by two newlines (it will work without the

    second newline, but that is not nice for the interfaces).

  - First line (the brief description) must only be one sentence and

    should start with a capital letter unless it starts with a lowercase

    symbol or identifier. Don't use a trailing period either. Don't exceed

    72 characters.

  - The main description (the body) is normal prose and should use normal

    punctuation and capital letters where appropriate. Normally, for patches

    sent to a mailing list it's copied from there.

  - When committing code on behalf of others use the --author option, e.g.

    git commit -a --author "Joe Coder <joe@coder.org>" and --signoff.

Code conventions

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

You may encounter old code that doesn't follow all the following code

conventions, but for new code it is better to follow them, for consistency.

  - Avoid trailing whitespace.

  - Indent the C code with tabulations with a width of eight characters.

  - The files should have a modeline for the indentation style.

  - All blocks should be surrounded by curly braces, even one-line blocks. It

    spaces out the code, and it is more convenient when some code must be added

    or removed without the need to add or remove the curly braces.

  - Follow the C89 standard. In particular, no "//"-style comments.

  - As a general rule of thumb, follow the same coding style as the surrounding

    code.

  - Do not be cheap about blank lines, spacing the code vertically help

    readability. However never use two consecutive blank lines, there is really

    no need.

Programming best practices

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

GtkSourceView is a pretty big piece of software, developed over the years by

different people and GNOME technologies. Some parts of the code may be a little

old. So when editing the code, we should try to make it better, not worse.

Here are some general advices.

  - Simplicity: the simpler code the better. Any trick that seem smart when you

    write it is going to bite your ass later when reading the code. Given that

    you spend 90% of the time staring at the code and 10% writing it, making

    reading the code harder is a net loss.

  - Brevity: make an effort to refactor common code into utility functions and

    use library function whenever is possible: every time you cut and paste a

    line of code you are throwing away all the precious seconds of your life

    that you will later spend trying to figure out the differences among the two

    copies that will have surely diverged.

  - Code for change: code is bound to contain bugs no matter how well it is

    written. A good coding style allows to fix these bugs with minimal changes

    instead of reformatting a whole section of unrelated code, this is

    especially important to make patch review easier and to easily understand

    the commit history. Some practical examples are:

      - Factor code into self contained functions so that changing a function

	does not require to change all the callers.

      - Do not align variable declaration, "case" statements etc, since this

	will inevitably mean that when a line will change you'll have to

	reformat all the surrounding ones.

      - Declare variables in the strictest scope as possible.

      - Reorder functions so that you do not need prototypes for static

	functions so that when you change them you need to change them only in

	one place.

  - Self documentation and code comments: use code comments parsimoniously. Code

    should be written so that it is clear and evident without the need of

    comments. Besides, comments usually get outdated when the code is changed

    and they become misleading. In particular avoid stating the obvious e.g. "a

    = 1; /* assign 1 to a */". Use good function names and variables to make the

    code self-documented.

    A good function name is one that explain clearly all what its code really

    does. There shouldn't be hidden features. If you can not find easily a good

    function name, you should probably split the function in smaller pieces. A

    function should do only one thing, but do it well.

    Please avoid lots of one-letter variables. And a variable should be used for

    only one purpose.

    Self-documentation is obviously not always possible, so when a comment is

    needed, it is needed. In those cases make sure to explain why and not only

    how a specific thing is done: you can deduce the "how" from the code, but

    not the "why".  Public library functions should always be documented and in

    particular should include the calling conventions, e.g. if the result should

    be freed by the caller.

    Do not use fancy frames around comments like a line full of

    /*---------------*/ etc.

  - Contribute below on the stack. Fix a problem at the right place, instead of

    writing hacks to work around a bug or a lack of feature in an underlying

    library.

See also

========

https://wiki.gnome.org/Apps/Gedit/DevGettingStarted

https://developer.gnome.org/programming-guidelines/stable/

https://wiki.gnome.org/Projects/GTK%2B/BestPractices

http://ometer.com/hacking.html

http://blogs.gnome.org/swilmet/2012/08/01/about-code-quality-and-maintainability/

For a shared library:

http://davidz25.blogspot.be/2011/07/writing-c-library-intro-conclusion-and.html

http://akkadia.org/drepper/

	- How to Write Shared Libraries

	- Good Practices in Library Design, Implementation, and Maintenance

Thanks,

  The GtkSourceView team.