README.coding

   1 **
   2 ** Source tree organization
   3 **
   4 ******************************************************
   5
   6  examples/ -> Supposed to be copy/pastable by the user, so keep it clear and
   7                 avoid any kind of trick. In particular, do only include the
   8                 public headers here.
   9
  10  teshsuite/ -> The more test the better. Put in there any strange test
  11                doing things that the users are not supposed to do,
  12                just to see if our framework is robust to incorrect and
  13                unusual behaviors. All tests written in this section
  14                should leverage our tesh(1) utility.
  15
  16 **
  17 ** NEW type naming standard in SimGrid4
  18 **
  19 *****************************************************
  20
  21 SimGrid4 will follow the these rules:
  22
  23   - filenames are unique in the whole project
  24     (because of a bug in Sonar coverage computation)
  25   C++
  26   - fields, methods and variables are in snake_case()
  27   - Classes and Enum names are in UpperCamelCase
  28   - Enum values are in UPPER_SNAKE_CASE (as constants)
  29   - public filenames: api_Class.cpp and api/Class.hpp.
  30     - Example: src/s4u/s4u_ConditionVariable.cpp and
  31                include/simgrid/s4u/ConditionVariable.hpp
  32     - If you prefer api_class.cpp, that's OK, too. Breath and relax.
  33       Example: src/s4u/s4u_actor.cpp and include/simgrid/s4u/Actor.hpp
  34   - internal/kernel filenames: Class.cpp and Class.hpp
  35     - Example: src/kernel/activity/Activity.cpp
  36                include/simgrid/activity/Activity.hpp
  37   C
  38   - variables and functions are in snake_case()
  39   - typedefs do not hide the pointers, ie * must be explicit
  40     char * sg_host_get_name(sg_host_t * host);
  41
  42
  43 This is different from the old convention (described below), that
  44 should not be used in S4U and its bindings, nor in the kernel.
  45
  46 **
  47 ** Commenting the source: doxygen
  48 **
  49 ****************************************************
  50
  51 The global structure of the documentation is in doc/modules.doc
  52
  53 The structure of each module (xbt, msg, etc) is in doc/module-<module>.doc
  54
  55 The structure of a module is in its public header. This way, you're sure to
  56 see all the public interface (and only it). The different parts of the
  57 interface are grouped using the @name construct, even if it's buggy. Since
  58 parts often get reordered, it's better to add numbers to the parts (so that
  59 users can see the intended order).
  60
  61 The documentation of each type and macro are also in the public header since
  62 this is were they live.
  63
  64 The documentation of each function must be in the C++ file were it lives.
  65
  66 Any public element (function, type and macro) must have a @brief part.
  67
  68 We use @ as a command marker, not \ (so, use @brief not \brief)
  69
  70 **
  71 ** OLD Type naming standard in SimGrid3
  72 **
  73 *****************************************************
  74
  75 SimGrid3 legacy interfaces (ie, MSG and SimDag) are following these rules:
  76
  77   - ???_t is a valid type (built with typedef)
  78   - s_toto_t is a structure (access to fields with .)
  79   - s_toto   is a structure needing 'struct' keyword to be used
  80   - e_toto_t is an enum
  81   - u_toto_t is an union
  82   - u_toto   is an union needing 'union' keyword to be used
  83   -   toto_t is an 'object' (struct*)
  84
  85 Please to not call toto_t something else than an 'object' (ie, something you
  86 have to call _new and _free on it).
  87
  88 Example:
  89   typedef struct s_toto {} s_toto_t, *toto_t;
  90   typedef enum {} e_toto_t;
  91
  92 Moreover, only toto_t (and e_toto_t) are public. The rest (mainly s_toto_t)
  93 is private.
  94
  95
  96 *
  97 * SimGrid Hacker Survival Guide (FIXME: should be betterly placed)
  98 ********************************
  99 * When you add/remove files, and/or make changes in the lists of files to build,
 100   please check that "make distcheck" still succeeds.  This is needed to ensure
 101   that the generated archive is consistent.