Changeset 175 for docs/trunk/hacking-guide

Legend:

Unmodified

Added

Removed

• docs/trunk/hacking-guide/tock-intro.tex

  r174	r175
  233	233	\section{Add Your Own Code}
  234	234
  235	%TODO explan any coding conventions (readability over all else?)
  235	Tock, as a project, does not have any particular coding conventions. Lists of module imports should be
  236	in alphabetical order, and that's about it. The code is littered with slightly curious code indentation,
  237	one or two letter variable names, incredibly long expressions stretching long and wide, various bits of
  238	uncommented code, and the use of many similar but different language features (e.g. if/then/else and
  239	pattern guards, map and list comprehensions), which may be blamed in varying measures on the current
  240	developers!
  241
  242	Which is not to say the code is bad, just that there is not tight control on coding style. In general:
  243
  244	\begin{enumerate}
  245	\item Use your common sense
  246	\item Vaguely follow the style of the existing code
  247	\item Favour readability and clarity over conciseness and cleverness
  248	\item Optimise in terms of algorithms (e.g. O($N \log N$) over O($N^2$)) but never look for small savings.
  249	Besides the effort being wasted, it would be very hard in Haskell to judge which of several pieces of
  250	code would be faster. The compiler does not have to be blindingly fast, but it does need to be
  251	maintainable.
  252	\item If a function foo is specifically needed by only the function bar, place foo inside the where
  253	clause of bar (unless this is particularly untenable). This keeps the code neater, and foo can always
  254	be moved to the top-level later if necessary.
  255	\item Try to provide type signatures for every function (i.e. anything of type a -> b -> c) in a where clause.
  256	Providing types for values in where clauses is also never a bad thing.
  257	\item Favour map, zip, etc over list comprehensions; it is usually neater.
  258	\item Never allow any possibility of a non-graceful run-time error. For example, do not use head, which
  259	can fail directly with a non-helpful error message. Instead, use a case statement (with a pattern-match),
  260	and in the case where the list is empty, use the die/dieP/dieInternal functions to provide a more helpful
  261	error message (such as ``list of types was not expected to be empty in function foo''). This is for
  262	practical reasons; if we used head everywhere in the code, then when the program failed with ``head: empty list''
  263	it would be very hard to work out exactly which instance of head had given the error. Similarly, try to
  264	ensure that you either always match all possible cases in pattern-matching, or you provide a default case that
  265	then gives an error message. Although this is not quite as crucial, because at least the error message
  266	for a failed pattern match gives the relevant line numbers.
  267	\end{enumerate}
  268
  269	As for other patterns of working: use the Tock mailing list (tock-discuss) for any questions you may have.
  270	All questions welcome, simple or complex, and asking there will save time, trouble, and should allow us
  271	to improve documentation such as this guide. It is especially worth asking if you want to revamp
  272	an existing section of code; other people may know of a reason why this is not wise, or may suggest a
  273	good way to go about it.
  236	274
  237	275	\section{Test Your Code}

Note: See TracChangeset for help on using the changeset viewer.