Code style - Revision history

Rcrowther at 15:40, 26 September 2016

2016-09-26T15:40:28Z

Frankier at 09:48, 20 June 2016

2016-06-20T09:48:49Z

Frankier: /* Do */

2016-06-14T16:44:07Z

Frankier: /* Don't */ Edit out example don'ts

2016-06-13T14:47:43Z

Don't: Edit out example don'ts

Frankier: /* Formatting/Syntax */

2016-06-12T14:15:29Z

Formatting/Syntax

Frankier: /* But if it's a dependency that's built in tree it's just a matter of getting the source there. It could be bootstrapped with a simple script or even (ick) vendorised into Subversion. */

2016-06-10T10:43:48Z

But if it's a dependency that's built in tree it's just a matter of getting the source there. It could be bootstrapped with a simple script or even (ick) vendorised into Subversion.

Frankier: --snark; ++helpfulness

2016-06-10T10:42:19Z

--snark; ++helpfulness

Frankier at 10:38, 10 June 2016

2016-06-10T10:38:36Z

Frankier at 07:28, 28 May 2016

2016-05-28T07:28:12Z

Frankier at 07:27, 28 May 2016

2016-05-28T07:27:13Z

← Older revision		Revision as of 15:40, 26 September 2016
Line 91:		Line 91:

	PEP-8?		PEP-8?

			[[Category:Documentation in English]]

@@ Line 35: / Line 35: @@
 It might be nice in future to use utf-8 everywhere inside Apertium and re-encode strings only when necessary at API boundaries. (Eg for stdio, re-encode to wstring and use wcout/wcerr only in environments with non-utf8 locale otherwise use cout/cerr). This could then be wrapped in a thin portable abstraction. There's some information about this way of doing things here: http://utf8everywhere.org/
+=== Exceptions ===
+Exceptions are in use, but the code doesn't follow the rules which would ensure it was exception safe. The strictest type of exception safety means that for every new/delete pair, either an smart pointer (auto_ptr, unique_ptr) should be used, or they should be used in a constructor/destructor pair. Currently MorphoStream doesn't meet this standard. This isn't (yet) a problem since most exceptions result in the program ending (and the whole process being deallocated by the OS).
 === I'd like to use $LIB eg Boost:Wurble or remove ifdefs by using eg gnulib ===

@@ Line 10: / Line 10: @@
 * Prefer C++ casts over C casts
 * Prefer the C++ stdlib over the C standard library
-* Prefer usage of smart pointers over manual memory management when stack/global allocation don't do the trick.
 * Prefer containers over home made data structures.

@@ Line 16: / Line 16: @@
 * Use void*
-* Use sprintf
-* If the pointer lifetime is the same as the object it refers to. Don't use a raw pointer.
 === String encoding ===

@@ Line 79: / Line 79: @@
 * another divergence is with variables that don't have a whole lot of information e.g. something being passed to a serialiser: they get bland names such as Stream and SerialisedType
 * since those are already used as type names -- just add a trailing underscore
+=== Sergio ===
+* Braces on separate lines
+* camelCase methods
+* snake_case local and member variables
+* UpperCamelCase class names
 = Python =

@@ Line 53: / Line 53: @@
 ==== But if it's a dependency that's built in tree it's just a matter of getting the source there. It could be bootstrapped with a simple script or even (ick) vendorised into Subversion. ====
-It could be considered if the situation were great enough and there was sufficient confidence it wouldn't make building harder, but the balance of argument is heavily against it. Implement whatever you need from scratch if it's small, or find a small library that does just what's needed to vendorise. Double check the functionality isn't already a utility in Apertium or Lttoolbox or part of an existing dependency.
+It could be considered if the benefit were great enough and there was sufficient confidence it wouldn't make building harder, but the balance of argument is heavily against it. Implement whatever you need from scratch if it's small, or find a small library that does just what's needed to vendorise. Double check the functionality isn't already a utility in Apertium or Lttoolbox or part of an existing dependency.
 == Formatting/Syntax ==

@@ Line 18: / Line 18: @@
 * Use sprintf
 * If the pointer lifetime is the same as the object it refers to. Don't use a raw pointer.
+=== String encoding ===
+==== Situation ====
+* There are lots of wstrings kept in memory about place. These are UTF-16 on Windows and UTF-32 on Linux.
+* There are also char* and strings which are UTF-8 encoded kept in memory in some places.
+* Mixing wide and narrow character streams is forbidden by the standard (http://stackoverflow.com/questions/8947949/mixing-cout-and-wcout-in-same-program) and also can also cause real problems in practice (https://gcc.gnu.org/bugzilla/show_bug.cgi?id=42552 https://sourceforge.net/p/apertium/tickets/106/).
+==== Approach ====
+* Use UTF-8 for serialising to files.
+* Use wcerr for outputting errors.
+* In terms of internal encodings, go with the flow for now.
+* You might have to use either wcout or cout depending on the situation but they shouldn't ever mix within the execution of a program. To help with this, follow the following rule: If you're expecting the program's output to be piped - don't output to wcout at all, just cout. If you're expecting the the output to end up on a terminal, use wcout.
+* If you have a UTF-8 string rather than an 7-bit clean ANSI string, you should UtfConverter::fromUtf8 it before outputting.
+==== Alternatives ====
+It might be nice in future to use utf-8 everywhere inside Apertium and re-encode strings only when necessary at API boundaries. (Eg for stdio, re-encode to wstring and use wcout/wcerr only in environments with non-utf8 locale otherwise use cout/cerr). This could then be wrapped in a thin portable abstraction. There's some information about this way of doing things here: http://utf8everywhere.org/
 === I'd like to use $LIB eg Boost:Wurble or remove ifdefs by using eg gnulib ===