My own thoughts about software development methodologies

work in progress draft
and it always will be

I wish to scatter some thoughts about the subject. There's no a particular order, deep analysis or claim for correctness.

• Defining the project and its requirements




• Do not let the developers define the requirements! Requirements come first, then it comes developing code (with feedback, if needed/required).




• Documenting APIs (if appropriate)




• Be brief and effective, do not add unuseful redundancy; it must be techinical, even when it is a "high level" API


• Let the dirty work be done automagically: force programmers to document into the code, using a special, fixed syntax (well-known or created ad hoc), but no literate programming — maybe with exceptions to be defined


• APIs' docs must not expose internals; if you need internals, put them in a separate document


• References and links, if appropriate; no copy-pasting


• If there's a protocol to access the API, describe it in a formal way (if it is a standard, just reference the standard document describing it, avoid giving your own incomplete simplistic description); if needed, train whoever has to understand the formal description, rather than sticking to a informal loosy description — which however is suitable as introduction and to give a general picture, if appropriate


• Do not use a format which is not mechanically parseable and that it is hard to be generated automatically. The best choice is still plain text with an agreed encoding (e.g. UTF-8) and line ending convention (e.g. LF, the "unix" way to terminate lines); however, for documents generated by source code, ASCII is likely the safer choice. TeX-based or HTML-based conventions for formatting are good ideas.


• Deploy the doc to the "rest of the world" in a read-only format, like PDF (which is likely also the best choice) — this implies the ability to generate the PDF from the "private" doc.


• Avoid translations: if your doc must be read "internationally", do it directly in english; in Europe, if it would be widespread, esperanto could be a fine choice... but alas it is still english that it is better to use! If people working in the project can't write/read "technical english" (to be distinguished from "literary english" and real-world english), teach it to them!




• Writing the code...




• Conventions! Train programmers to use an agreed set of conventions (tabs, spaces, indenting, symbols' and variables' names, comments' style...)


• Comment, but not too much; avoid "line by line" comments, prefer "logical block" comments


• This is not always true but... more data structures, less code!


• Break functionalities into as small as possible functions/objects (depending on programming paradigm in use)


• Think functions as reusable bricks, leave room for enhancements without breaking existing working code (this is easier in OO programming, nonetheless it is not impossible in non-OO programming)


• Refactor your code; possibly before it becomes a mess; even when this happens, refactor it anyway, it is not a waste of time/money (at least not in the long run), it is needed to keep your code manageable and...


• Refactor before your code becomes unmanageable, and refactor/redesign if your code is already hardly manageable; this sometimes could be done in small steps while developing other features


• Use well-known (in the community of your language) libraries, rather than your own implementation (if there are no licensing issues); but of course if you can't find what you need, take your time to implement it rather than sticking to other possible but poor solutions


• Don't waste time for optimizations, if your bottle-necks are elsewhere! (Profile your code to see where it is slow, and optimize there!)


• If your language misses a hashtable and you need to choose actions according to a "pattern" given as input, ... find a hashtable implementation/library rather than using a long list of if-then-elseif or a C-like switch. Match this suggestion with the optimization topic if appropriate; if not, consider that the hash-approach produces clea(n/r)er code, as "more data structures, less code" does! (In fact the specific hashtable example is about following the suggestion "more data structures, less code", avoiding linear search.)


• The previous reasoning on the hashtable is applicable to other features too, with the appropriate changes


• Avoid copy-pasting; sometimes it is not so bad, but if you do it or need it too often, it means your code is badly designed/implemented... time for refactoring!


• Test functionalities apart; e.g. write "toy code" and check its output given a specific input


• Do not use so called Hungarian Notation; if to you it's an issue, use a good IDE to help you!


• Use meaningful names for symbols/variables; but iterations in language having no special syntax to iterate over a "collection" (or a slice of it) can (should!) use short common names for indexes (like i j k n m).