Algorithms instead of source code !!

Submitted ⁨⁨10⁩ ⁨months⁩ ago⁩ by ⁨erranto@lemmy.world⁩ to ⁨programming@programming.dev⁩

Disclaimer : I am a hobbyist programmer have gone to Uni for that , so I might not know everything I am talking about.

My question is why don’t open source programs include something like diagrams of the algorithms they employ ?? I Was looking for algorithms for a chat program with client-server architecture, I was hoping to find diagrams and descriptions of how algorithms work, so a to study them an adapt them to my needs. All I found were FOSS projects with no such documentation.

Considering that reading source code can take a long time, and sometimes interesting projects are written in a language the user isn’t familiar with, I was wondering why such documentation style doesn’t exist ? It could help even newer contributors get started quicker.

source

Comments

Sort:hotnew top

ninjan@lemmy.mildgrim.com ⁨10⁩ ⁨months⁩ ago
The answer to this question is the same as for all documentation:

Because it’s boring to write documentation

What is obvious and what needs to be explained is often not apparent for the person creating it

When time is limited then documentation is the first thing to be reduced

Not enough value is put on good documentation and the associated skill

But in the spirit of FOSS documentation is something that is actually an excellent thing for a person new the project to start contributing to. You need to understand the code anyway to be able to help with bugfixes / feature creation so might as well build reputation by improving on existing documentation by adding clarification and comments and wiki entries that would’ve aided in making it quicker for you to grasp something.
source
- MagicShel@programming.dev ⁨10⁩ ⁨months⁩ ago
  Also, it’s not just that it’s boring, difficult, and undervalued, but also during development the code is constantly changing and to constantly spend 20 minutes updating documentation for a 3 minute change that might or might not solve an issue is horribly wasteful of time. So by the time a project releases, probably 80% of the documentation is outdated already.
  
  The only exception to this I’m familiar with (though I’m sure there are others) is using OpenAPI to generate both source code and documentation from a configuration file. That way your documentation and code are always in sync. But that’s a relatively narrow use case that isn’t going to cover low-level stuff like algorithms.
  
  source
nullPointer@programming.dev ⁨10⁩ ⁨months⁩ ago
“algorithm” is a little too fine grained for what you describe. “software design patterns” is probably what you are looking for.

unfortunately, not all projects call out the patterns they employ.

source
justJanne@startrek.website ⁨10⁩ ⁨months⁩ ago

Considering that reading source code can take a long time

You’ll get faster over time, until reading code is faster than reading documentation, as code will always represent what’s truly happening, while docs are frequently outdated.

In a language the user isn’t familiar with

If you’re not that familiar, it’s likely you won’t be contributing to the project. Open source projects usually to have quite limited resources, so they tend to optimize docs and dev UX for people who are likely to contribute.

source
- erranto@lemmy.world ⁨10⁩ ⁨months⁩ ago
  
  If you’re not that familiar with the language, it’s likely you won’t be contributing to the project.
  
  You can still borrow and implement features developed by project x into project y , but I do understand the time limitation.
  
  because I am more of a visual learner I wondered whether developers don’t use diagrams and flow charts, or just don’t include them in the docs.
  
  source
  - YIj54yALOJxEsY20eU@lemm.ee ⁨10⁩ ⁨months⁩ ago
    Personally I will jot some loose notes down if I’m implementing something that requires it, but formalizing the design patterns/algorithms is very time consuming so I don’t.
    
    source
DrDeadCrash@programming.dev ⁨10⁩ ⁨months⁩ ago
Being able to document the exact algorithms used to solve a problem is sort of a ‘Holy Grail’ in programming. Most programmers aren’t afforded the time to document to that level. This would require refining the code down to a single cohesive story that describes the functionality of the implementation. It’s great when you can spend the time on it, but the problem is that the code is actually “working” long before that point. Most employers want to stop paying for code after it starts working.

source
amio@kbin.social ⁨10⁩ ⁨months⁩ ago
There's no point spending twice the time making something that corresponds 1:1 to code - unless the code is truly horrific, and then you've got bigger issues. One generally assumes people involved with a project will know or learn relevant languages.

It's more commonly used for things that are less obvious from the source itself - like "what's sent between the client and server in this handshake" or "what is the overall architecture of this part of the code"

Flowcharts may be a bit more common when studying algorithms in general

source
Disregard3145@lemmy.world ⁨10⁩ ⁨months⁩ ago
I think you’re describing protocols rather than algorithms For a chat program you can look at xmpp, or matrix, both are open protocols for chat apps. You can find info about how they communicate in RFCs or Google “xmpp architecture”

en.m.wikipedia.org/wiki/XMPP links to the RFCs for that.

source
Diplomjodler@feddit.de ⁨10⁩ ⁨months⁩ ago
Most software is poorly documented. That applies to FOSS as much as to commercial projects.

source
vhstape@lemmy.sdf.org ⁨10⁩ ⁨months⁩ ago
I am in the habit of writing verbose comments in my source code, which includes attributing the algorithms used and where I found information thereon. Unfortunately, this is not common practice… Be the change you want to see!

source
bizdelnick@lemmy.ml ⁨10⁩ ⁨months⁩ ago
There are a lot of books describing algorithms. Most network protocols are described in RFCs as well as advices on their implementation. So you are looking in the wrong place. Source code documentation is usually enough to be understood by coders who are already familiar with common algorithms, protocols and APIs or know where to find their description. Only things that are very specific to the project can be described in details.

source
ericjmorey@programming.dev ⁨10⁩ ⁨months⁩ ago
I’m very unclear about what you’re asking. Do you have an example of something you’ve created that includes what you’re talking about?

source
- supernicepojo@lemmy.world ⁨10⁩ ⁨months⁩ ago
  I think they mean like a flow chart or another visual aid to show data changes and information flow through a program. Ive never seen anything like what they are asking for either in documentation, only in code meetings or developer charts.
  
  source
  - erranto@lemmy.world ⁨10⁩ ⁨months⁩ ago
    Exactly what I was referring to. its the type of flow charts you find included in some whitepapers as well.
    
    source
    -> View More Comments
- erranto@lemmy.world ⁨10⁩ ⁨months⁩ ago
  No, I haven’t started my project yet. I was looking for docs with descriptions and diagrams about server-client chat algorithms. And I haven’t found any, that’s why I am asking!
  
  source