“historische” Richtlinien für Abschlussarbeiten der Gruppe von Prof. Fuhr - to a large extent still applicable for us as well
The following are slogans from Agile philosophy. Not all of them should be followed slavishly, but there is certain truth to them. Maybe google for them and read a bit.
Commits should be frequent, small and atomic.
If you can’t commit (push) before going home, revert.
Never break the master build. (Use continuous integration whenever possible.)
Die, long-lived branches!
Commit messages should be informative (instead of “updated Types.hs”, rather “added a tree datatype”).
Use spaces instead of tabs. (Configure your editor accordingly.)
To prevent incompatibilities in different operating systems, do not use filenames that contain spaces or underscores or Umlauts. Also, no two filenames that differ only via capitalization.
In Haskell specifically:
In probably more than 90% of occurrences, use of fromJust is a mistake (i.e., is bad coding).
Using nub is almost never a good idea. Use nubOrd (or even nubSort) instead.
Writing your own recursions on lists is very rarely necessary. Usually, list comprehensions or existing (higher-order) functions, or combinations thereof, are a better fit.
Make use of https://hoogle.haskell.org/ to search for existing functionality (by name or by type) instead of implementing all kinds of auxiliary functions yourself. Specifically, the extra package is a good source of helper functions.
Make conscious decisions about using Int vs. using Integer.
Use fromIntegral instead of fromInteger or toInteger.
Mostly avoid introducing type synonyms via type. Instead, use data or newtype where appropriate.
Use anonymous functions where appropriate. (Sometimes not introducing a name is a good way of not introducing a bad name.)
If a named entity, like a let-introduced value or a top-level function, has a very short definition and moreover is used only exactly once in the rest of the code, it is sometimes better to simply inline it directly instead. (Indeed: Sometimes not introducing a name is a good way of not introducing a bad name.)
Use explicit export lists. Make them as short as possible in each module.
Mostly use explicit import lists. Read https://wiki.haskell.org/Import_modules_properly and consider their advice.
Read and largely follow some Haskell style guide.
Use stack, not (plain) cabal.
Use HLint.
Use ghc -Wall (possibly covered by the stack setup).
Use stack test --coverage; stack hpc report --all --open (locally, regularly).
Generally, when structuring your codebase, think about (and if necessary, first google for) “cohesion and (loose) coupling”.
For test suites, always consider writing also negative test cases.
You may also want to read up on some other notions and techniques from Agile software engineering. Such as:
Timeboxing
Minimum Viable Product
Kanban/Scrum Boards
Definition of Done
Always in this way:
concrete code is committed and pushed to repository (maybe in a separate branch only meant for reporting the problem),
an issue is opened, in which the problem (“code from branch/commit so-and-so exhibits …”) is explained:
problem / error message / desired result.
Also, whenever possible, provide an SSCCE.
If you have not worked with git before, and are a Windows or macOS user, consider installing and using GitHub Desktop. Some of the CLI instructions below are then less relevant for you. In any case, always work with a proper repository set up on your local machine, not with a disconnected local directory and manual uploads via the GitHub web interface!
Run git config --global pull.rebase true or git config --local pull.rebase true in the relevant clone of the repository, once up front.
Use the power of git add -p or an equivalent “hunk staging” functionality in your Git client.
Avoid/prevent spurious diffs!
Prevent “whitespace errors” using editor settings (or use https://github.com/RichardBronosky/git-fix-whitespace regularly).
Mostly superfluous if adhering to the previous point: Execute git diff --staged --check between git add and git commit (or use an equivalent workflow in a non-CLI Git client).
Note that the editor settings mentioned above (and provided by us as an .editorconfig file) can be enforced by most editors either directly or after installing some plugin.
On GitHub, e.g., in issues and comments, use markup for code etc. (Generally, google for “GitHub Flavored Markdown”.)
Where appropriate (possibly on GitHub and in Slack), make use of GitHub permalinks.
Possibly use GitHub project boards in the repository, in the spirit of Kanban/Scrum or elsewise.
Please watch this video and follow its advice: How To Write Papers So People Can Read Them - YouTube
Start writing almost immediately after the work has started, recording ideas, concepts, initial developments, etc.
Use LaTeX and appropriate packages (e.g., for diagram visualizations).
Put the LaTeX source code under version control in the same GitHub repository as the program code being developed. (Do this even in case you are using Overleaf - it does have an option for GitHub synchronization.)
A good habit to prevent largish Git diffs in LaTeX source code is to put each sentence on its own line.
Do not use \\ or \newline to structure flowing text in LaTeX. Instead, use empty lines. Uses of \newpage or \pagebreak are mostly also a code smell in LaTeX.
Use a spell checker! Always! Ideally in on-the-fly mode.
Besides GitHub Issues, possibly also use the in-Slack bookmarks feature to keep track of things you have to do, react to, etc.
Use Slack for Desktop on your operating system. (That is, not just the mobile or browser version.)
When starting a thread by answering one’s own (or GitHub’s) message, it is possible that nobody else notices the new one, due to the way Slack notifications work. Better then to use the “also send to channel” option.
Since the GitHub to Slack notification route does not always work reliably, make sure to also have another notification measure turned on for the repository, e.g., notification via email.
Take a look at https://fmidue.github.io/ba-ma-template/ from time to time.