Code is not self documenting..

reading 10k+ lines of business logic does not take the place of well defined documentation.

Mic drop.

People who think their code is self documenting should tell me about their code .... 6 months from now ;)

@N00bPancakes Let alone read ones own code. :p

Well some code could be its own documentation. But such a thing is rare. So to the longest extentent possible I guess one should strive towards self documenting code, but comment where that isn’t the case.

See domain modelling

@N00bPancakes hell I just wrote a few thousand at most line node script and I think a paradigm change is already in order

@craig939393 oh god that looks like a flow chart or that failed Uml shit no one uses lol

@craig939393 nothing replaces a good well documented set of tree arranged features and change requests

In my opinion for planning

Though I do use flowcharts for small things sometimes only a bit more high level

@LiquidOfLife I agree that there are cases, but when your ba tells you to review the code to get the idea of how the system permissions should be...

They are wrong. 😂

@MadMadMadMrMim that's not domain modelling. I started learning the engineering part of software engineering a few years ago, so I don't mean this to be rude at all - you should have a look at model driven design (an aspect of domain driven development) and my point about self documenting code will become more apparent.

@craig939393 not taken as being rude
We had glyphs and charts and graphics for sales.
But we’d have a meeting every morning to discuss status and plan changes after discussions with the client and document then and everything was pretty much based off familiarity with the design
I’ll have a look but to me seems a tad tedious if you’re getting really low level
A graph showing user permissions and service users and their interaction would be useful to me but yeah I’ll have a look and comment more

@craig939393 so the sight I saw mentioned what we used Agile where you plan endpoints and interfaces so people can work simultaneously

And generators we use those
Explain a bit further I saw marketing lingo trying to sell the method so they could charge to teach it

Any good links ?

@MadMadMadMrMim domain driven design is a big philosophy for development put forward by Eric Evans in a book titled domain driven design. Many companies require knowledge of it for higher level jobs.

The coding aspect of model driven design is focused on a few different aspects but the main part is aggregate roots. An aggregate root is an object that references other objects and controls access to them. Eg to get to orders a customer has purchased you must first get a reference to a customer. customer.Orders() or customer.placeOrder(), never database.Orders() or database.createOrder().

The point of this is to create high cohesion objects, you have a single source of truth for your business logic (your domain model) and business logic that involves two different objects is in the aggregate. Therefore your logic cannot leak into other areas of the system creating duplicate code or conflicting features.

Pair with clean code where you focus on telling a story in code.

@MadMadMadMrMim every line as abstract as the others in a method and you end up with methods called in almost plain English one after the other.

There is more in DDD than this, but to not go into other aspects and their advantages we can already say we have code that that keeps business logic only where it should be, and when reading the code there will be areas that only specify what to do in plain English. Therefore the code reflects business logic really well, and is easy to read. Hence it is self documenting of both the business logic aspect and hopefully the technical aspect.

@MadMadMadMrMim I forgot to say - you may have noticed I didn't mention diagrams. Diagrams are only to help show your model if you want to, especially if you're trying to share your model on the internet you will probably want a diagram. Model driven design and diagrams are different topics.

@craig939393 that sounds like a business object layer

@craig939393 I mean seriously like you’re describing some pretty standard things

Like for example isolating as much of that logic as possible in stored procedures for example that check all these things prior to creating an object and generating a code layer with hooks to the db end

Kind of just sounds like normal ntier like software dev using agile scrum

@MadMadMadMrMim it's not ntier but yes domain modelling is a common term and all software has a domain model. The trick is to make a good one and DDD teaches how. If you watch talks or read blogs from experts like Martin Fowler, Kent Beck, Allen Hollub, Robert Martin, they will all mention DDD. Indeed their books often reference DDD. Still it's hard to explain a decent sized book on devrant. I recommend giving it a read if only because if you keep an eye out for DDD in future you might realise a lot of people mention it even in job adverts. In my opinion any Dev that reads it and has some idea of SOLID and maybe GOF patterns going in, will wonder why no one has ever taught us this stuff. It's a travesty of our industry that hardly any 'seniors' know how to domain model / design busines logic and so don't teach juniors.

The code that I maintained had documentation but It's already outdated. I try to follow installation instructions but my code still not working. I tried fix the error by copy paste the error to google and implement some stackoverflow answer but still no luck. I end up ssh in to production server copy the application code, dependencies and table schema and finally it's work without error. It took me 3 months just to install the application.

@N00bPancakes it’s still self documenting, ofc 🙄

Just... it’s in ancient Chinese 🌝

you know i'm pretty sure that someone was playing a fucked up game to make me think that everytime I have a conversation with someone i'm inviting them to hurt a kid, and that they will engage in these activities based off little or no prompting, not simply just want to and that this was intended to push me towards extremely violent actions against them because this was convenient for someone.

Some languages are better suited for self-documentation.

It helps if you have short well defined methods and clear OOP to follow. Keep it DRY and it's actually pretty easy to have minimal comments.

@sariel which programming language that suited for self documentation? Can you give an example?

In my personal experience, if code is well formatted and follows a defined style standard, I can get a good feel of things after a quick skim. But I agree, if someone just threw together something without thinking, it can be difficult.

You found another shitty code base that nobody understands. And you think that the missing comments is the problem. It’s not.

As with everything, good balance of both is the real answer. You can really write self documenting code but you really need to dedicate yourself AND your team to it. It doesn't help if you are the only person doing it. Everyone needs to know that they have to do it and HOW to do it.

That said, some concepts in a big codebase should be documented, but in a separate document explaining the ideas and how it was solved on the high level. The higher level it is, the less stale it will become during changes, BUT higher level also means more complicated, so tradeoff there is to keep it simple as possible.

The point of programming in a high level language and documentation is to help humans understand code, not machines. Everybody should always write the code for other developers first, themselves second, and machine last. Except when optimized code is required, but MOST of the time it is not.

@BimaAdi ruby is my best example. PHP can be if OOP best practices are followed.

Go, crystal, elixir, all can be self documenting if it's not written by a Jr dev.

It is, if the whole code block fits in less than 50 lines.

That would mean your functions are self documented, but you still have to provide a general description h
Of how things work, what calls what, what is the logic behind it, etc.

Code doe anot replace project documentation.

Some code doesn't need documentation, some does.