apps/konsole/developer-doc/README

   1
   2 Developer Documentation for Konsole
   3
   4 Authors:        Robert Knight < robertknight@gmail.com >
   5 Last Updated:   7th May 2007
   6 Summary:        Introduction to Konsole developer documentation
   7 ===============================================================
   8
   9 Contents:
  10
  11 1.      Introduction
  12 2.      Documentation format
  13 3.      Documentation layout (aka. 'Where to find things')
  14 4.      Contributing to Konsole
  15     4.1     Discussion and help
  16     4.2     Submitting code
  17     4.2.1   API documentation guidelines
  18     4.2.2   Code style guidelines
  19
  20 ===============================================================
  21
  22 1.  Introduction
  23
  24 This document explains the layout of the developer documentation folder,
  25 and basic guidelines for contributors.
  26
  27 2.  Documentation format
  28
  29 To try and make it easier for developers to find the information they need
  30 about Konsole, the use of a standard document template which answers the following
  31 questions is encouraged:
  32
  33     - What is this document?
  34     - Who wrote it?
  35     - When was it last updated?
  36     - What is it about?
  37     - Where can I find information about <subject> within this document?
  38
  39 The current template can be found in design/developer-documentation-template
  40
  41 There is older documentation in the old-documents/ folder which does
  42 not follow this format.  This is kept as a reference.  Assistance
  43 in tidying up documentation from that directory by using the documentation
  44 template would be appreciated.
  45
  46 3.  Documentation layout
  47
  48     design/           - Documentation about the design of Konsole, and templates
  49                         for developer documentation.
  50     design/historic   - Documentation which was prepared during the KDE 4.0x development
  51                         cycle but which is no longer relevant.
  52
  53     research/         - Results of research into user's experiences with Konsole
  54
  55     user-interface/   - Documentation concerning design and analysis of the user interface.
  56
  57     old-documents/  - An assortment of documentation which was created during earlier
  58                       releases of Konsole.  There is useful inforamtion here, particularly
  59                       about the type of terminal which Konsole emulates, but it is not
  60                       organised.
  61
  62 4.  Contributing to Konsole
  63
  64 Help with Konsole's development, whether it involves code, user interface suggestions or
  65 other resources is greatly appreciated.
  66
  67 4.1 Discussion and help
  68
  69 Discussion about Konsole development takes place primarily on the Konsole mailing list,
  70 at konsole-devel@kde.org.  If you need help with Konsole development or wish to discuss
  71 implementation of a feature, fixes to bugs etc., then this is an appropriate place to
  72 do that.
  73
  74 4.2  Submitting code
  75
  76 Patches can be submitted for Konsole in a number of places:
  77
  78     - For bugfixes, we recommend that you attach the patch to the relevant bug report on bugs.kde.org
  79     - For new features, a patch can be attached to a relevant wishlist report on bugs.kde.org if
  80       there is one, and/or submitted to konsole-devel@kde.org
  81
  82     If your patch adds new methods or classes then please ensure that there is API documentation for
  83     them in the code.  Looking at the header files for existing classes should give you an idea of
  84     what is asked for.
  85
  86
  87 4.2.1  API documentation guidelines
  88
  89    Good API documentation in the code is very helpful for other developers.  Here are a few guidelines on
  90    writing API documentation for Konsole:
  91
  92         - All classes should have documentation which describes the basic function of the class.
  93           Usage examples are appreciated.
  94         - All public and protected methods should have API documentation which describes what
  95           the method does and what the returned value (if any) means.
  96           Parameter documentation is encouraged if the method has more than a couple of parameters
  97           or if the use of a parameter is not immediately clear from its name and type.
  98         - All public and protected enumerations and constants should have API documentation which
  99           describes what the various values mean.
 100         - The usage of brief standard comments next to private methods is encouraged to
 101           provide a quick explanation of what that method does.
 102
 103 4.2.2   Code style guidelines
 104
 105     The API style roughly follows that used in the Qt and KDE classes.
 106
 107     There are no strict guidelines on aspects of the code such as indentation, braces
 108     or spacing, although following the style of the existing code is a good idea.
 109
 110     Below is a list of the most important style considerations which have been developed
 111     following experience working on earlier Konsole code:
 112
 113     - Variables and methods should have CLEAR, verbose names.  The use of abbreviations
 114       should be avoided except for very common cases.
 115
 116     - The use of named constants is preferred over literals for clarity, and also to prevent
 117       the need to edit each instance of a literal if the value needs to be changed.
 118
 119     - The use of macros ( #define ) should be avoided where possible.  enums, inline methods
 120       templates, static constants etc. are strongly preferred.
 121     - Inside classes, private member fields have an underscore prefix ( eg. _myPrivateField )
 122     - Private slots in classes DO NOT have a "slot" prefix before their name which is often
 123       seen in other KDE applications.
 124
 125     Earlier Konsole code had a proliferation of two-letter variable names, which made it hard
 126     to read and understand in some places, and let directly to bugs in others.  Descriptive naming
 127     and sensible use of comments are strongly encouraged in new code.
 128
 129
 130
 131