40
submitted 10 months ago* (last edited 10 months ago) by erranto@lemmy.world to c/programming@programming.dev

Disclaimer : I am a hobbyist programmer, I have not 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.

top 19 comments
sorted by: hot top controversial new old
[-] ninjan@lemmy.mildgrim.com 39 points 10 months ago

The answer to this question is the same as for all documentation:

  1. Because it's boring to write documentation
  2. What is obvious and what needs to be explained is often not apparent for the person creating it
  3. When time is limited then documentation is the first thing to be reduced
  4. 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.

[-] MagicShel@programming.dev 17 points 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.

[-] nullPointer@programming.dev 23 points 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.

[-] DrDeadCrash@programming.dev 14 points 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.

[-] amio@kbin.social 14 points 10 months ago* (last edited 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

Edit; from your other comments, you seem to be talking about protocols, not algorithms. An algorithm is a set of steps to do something. A protocol is a description of how different systems interact such as in a chat application.

[-] justJanne@startrek.website 13 points 10 months ago* (last edited 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 with the language, 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.

[-] erranto@lemmy.world 4 points 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.

[-] YIj54yALOJxEsY20eU@lemm.ee 3 points 10 months ago* (last edited 10 months ago)

Personally I will jot some loose notes down if I'm implementing something thats sufficiently difficult, but formalizing the design patterns/algorithms is very time consuming so I don't.

[-] Disregard3145@lemmy.world 11 points 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"

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

[-] Diplomjodler@feddit.de 8 points 10 months ago

Most software is poorly documented. That applies to FOSS as much as to commercial projects.

[-] vhstape@lemmy.sdf.org 6 points 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!

[-] ericjmorey@programming.dev 3 points 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?

[-] supernicepojo@lemmy.world 4 points 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.

[-] erranto@lemmy.world 3 points 10 months ago

Exactly what I was referring to. its the type of flow charts you find included in some whitepapers as well.

[-] orbitz@lemmy.ca 2 points 10 months ago

The problem with stuff like flow charts is that when you do a new feature that changes the chart then there's another chunk of time to update that document. If you're really interested in that all you can really do is make your own as you go through software and you'll see usual patterns how different code areas interact. it's not as useful as figuring it out on your own or studying design paradigms.

[-] erranto@lemmy.world 2 points 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!

[-] bizdelnick@lemmy.ml 3 points 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.

[-] Lmaydev@programming.dev 2 points 9 months ago

At the end of the day it's a lot of effort.

People are already giving up their free time to write code.

Very few companies even have this.

[-] atheken@programming.dev 1 points 9 months ago

You are really looking for architecture diagrams. These are extremely rare in most projects, open source or otherwise.

The reason you don’t see a lot of documentation on algorithms used or architecture is that most of the time the code is not actually novel. It’s like asking a plumber to describe the physical properties of the pipe they used on a job. They’d say “schedule 40” or “copper” and a dimension. They would not describe the manufacturing process or chemical composition of the pipe. The materials are pretty standard and only require special descriptions for when and why they deviate from those standards.

this post was submitted on 17 Jan 2024
40 points (93.5% liked)

Programming

17314 readers
94 users here now

Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!

Cross posting is strongly encouraged in the instance. If you feel your post or another person's post makes sense in another community cross post into it.

Hope you enjoy the instance!

Rules

Rules

  • Follow the programming.dev instance rules
  • Keep content related to programming in some way
  • If you're posting long videos try to add in some form of tldr for those who don't want to watch videos

Wormhole

Follow the wormhole through a path of communities !webdev@programming.dev



founded 1 year ago
MODERATORS