Splitcells Network's Guidelines

Guidelines are just that. They are nothing more and nothing less. If these guidelines are overridden a reason should be present, and be documented or commented, if it is feasible.

For (programming) languages and document formats prefer using the most official or the most common guidelines, if there are no guidelines of this project applying to the aspect in question. In other words, language and documentation specific guidelines of this project try to only override public guidelines instead of writing complete custom guidelines from scratch.

The project structure, its contents and products has to represent a discovery based network of perspectives and changes. The project and its parts should be portable, extendable, adaptable, deletable and comply with Perspective's guidelines .

This specifically means, that the file and content path of a particular information (for an XML element, this would be the file path + the XPath pointing to the XML element) should identify and describe or at least summarize the content's meaning. This also means, that in an ideal case, one should be able to guess, where to look, for a particular content without knowing where the files are located

wide screen

I created these code guidelines in order to do some thought experiments. Do not consider these code guidelines for your own code. If you do, people will hate you, and you’ll be scorned by friends and family. 

  1. Goals
  2. Base Rule
  1.  Open Tasks 
  1. guidelines
    1. backwards-compatibility.html
    2. changelog.html
    3. chezmoi.html
    4. commonmark.html
    5. complexity-management.html
    6. dependency.html
    7. documentation.html
    8. filesystem.html
    9. gist
      1. git.html
      2. pgp.html
    10. html.html
    11. index.html
    12. infrastructure.html
    13. java.html
    14. licensing.html
    15. linking.html
    16. maven.html
    17. program-code.html
    18. project.html
    19. python.html
    20. shell.html
    21. software-project-file-system-standards.html
    22. software-project-file-system-standards.todo.html
    23. source-code.html
    24. source-types.html
    25. task-management.html
    26. technology-stack.html
    27. test.html
    28. tickets.html
    29. xml.html
    30. xslt.html
  1. guidelines
    1. infrastructure.html
    2. complexity-management.html
    3. test.html
    4. backwards-compatibility.html
    5. java.html
    6. linking.html
    7. changelog.html
    8. commonmark.html
    9. licensing.html
    10. program-code.html
    11. xml.html
    12. technology-stack.html
    13. chezmoi.html
    14. maven.html
    15. project.html
    16. dependency.html
    17. documentation.html
    18. gist
      1. git.html
      2. pgp.html
    19. task-management.html
    20. source-code.html
    21. tickets.html
    22. xslt.html
    23. source-types.html
    24. python.html
    25. shell.html
    26. software-project-file-system-standards.todo.html
    27. index.html
    28. project.partitioning.svg
    29. html.html
    30. filesystem.html
    31. software-project-file-system-standards.html
    1. d:toDo
      1. Minimize guideline.

    2. d:toDo
      1. Move framework specific guides to framework documentation or delete it, if this is covered by frameworks API.

    3. d:toDo
      1. Document dependency lifecycle of injection and integration.

    4. d:todo
      1. Meta Code Guidelines

      2. d:todo
        1. https://github.com/icy/bash-coding-style

      3. d:todo
        1. http://localhost:4000/white/index.html

      1. d:todo
        1. assertions (error detecting during execution and testing)

        2. d:todo
          1. When to use assertions and when not.

        3. d:todo
          1. Assert condition on actual objects directly. Do not assert variables representing the presence of a condition, as it makes debugging and error reporting harder. https://blog.smartcoders.xyz/2018/02/14/asserttrue-vs-assertthat-vs-assertj/

        4. d:todo
          1. Assertions should have access to the underlining objects for better error reporting.

      2. d:todo
        1. consistency checks

      3. d:todo
        1. unit test

      4. d:todo
        1. integration test

      5. d:todo
        1. complete test

      6. d:todo
        1. naming conventions: suffixes

      7. d:todo
        1. naming conventions: verb, attribute, getter and setter

      8. d:todo
        1. naming conventions: Ensure state via active verbs as it makes short names and allows inefficient but simple implementations. i.e. package.state(INSTALLED) -> package.install (Note that the first version makes more sense in some cases. The first one can also be implemented as a wrapper for the second one.)

      9. d:todo
        1. up cast convention

      10. d:todo
        1. side effect free interfaces

      11. d:todo
        1. down cast convention: down casted objects should be not lead to interfaces with side effects (i.e. parting collection interface in multiple interfaces representing different access rights.).

      12. d:todo
        1. technical and domain specific interface: inheritance and composition rule

      13. d:todo
        1. Minimize the number of current migration to 1 migration per component.

      14. d:todo
        1. Avoid assertThat((boolean) ...)... in AssertJ as one may forget to write isTrue().

      15. d:todo
        1. Multi thread/process programming should not be about thread/process but about removing instruction dependencies.

      16. d:todo
        1. Every persistent task is part of a software project or a software project itself and should be contained inside a folder.

        2. d:todo
          1. A software project is metadata like the .git files of Git repositories. Another example are the .idea folders of Intellji IDE projects.

        3. d:todo
          1. If multiple software projects are added to the task folder, it is preferred to add software projects to the task folder. Wrapping the task folder with software projects recursively does not scale.

          2. d:todo
            1. If possible one could create a software project folder inside the folder where all software project files are put. Make sure to make the folder name unique i.e. ".meta.238" .

      17. d:todo
        1. Make all assumtions visible (i.e. nullable variables via Optional).

      18. d:todo
        1. https://devhints.io/

      19. d:todo
        1. https://www.jwz.org/doc/worse-is-better.html

        2. d:todo
          1. Make consistent by making more simple things the consistent ones.

        3. d:todo
          1. Make correct by making more simple things the correct ones.

      20. d:toDo
        1. Avoid software rewrites and prefer migration based development.

      21. d:toDo
        1. Projects are likely to grow and get out of scope.

      22. d:toDo
        1. Fork, join and cathedral development protocol.

      23. d:toDo
        1. Programs should be primarily seen as tree/table transformers in order to simplify programming paradigm and language use.

      24. d:toDo
        1. Migration based Development

      25. d:toDo
        1. Configuration automation guidelines.

      26. d:toDo
        1. Make it possible to tolerate out of date documentation.

      27. d:toDo
        1. Create containment protocol for side effects in Java code.