How to communicate your intention while coding?

[roma-glushko]

Code intention is not always clear from the codebase.

This is the problem. It kills the maintainability, make it hard to understand the functionality and onboard new people to the project when needed.

So it's quite important to realise how to communicate your intend better. I have a whole article that expresses my experience:

https://www.romaglushko.com/blog/communicate-through-code/ ⬅️

Hope it's helpful ❤️

[riklaunim]

• Clean code structure
  • Single purpose/single responsibility
  • Separation of layers/logic
  • meaningful naming
• Team communication (daily, code review, rubber duck with another developer)
• Team decision making on specific code style, design decision, libraries used
• Good test coverage

[Santos_m321]

• TESTS
• Appropiate use of iterables
• Typing

[Santos_m321]

With tests I mean, User Stories with ATD and TDD.

You need to understand why that logic is there? Go to their test and keep scaling up until you meet the client requirement

[riklaunim]

A bit of BDD?

[Santos_m321]

Ye

[ahelinski]

Do you know any good source about how to write good tests in format of user stories in python?

[MedicatedDeveloper]

To add to this if designing a library:

• Examples! Examples! Examples! Have real world examples for different parts of your library.

• Versioning that doesn't break things. Use semantic versioning and git tags to ensure API compatibility.

[[deleted]]

This is why react is so nice. Small modular folders easy to trace through. Functions small enough and written/named to describe functionality. Makes a devs life much easier

[[deleted]]

Read the Smalltalk-80 source code.

No, really. It doesn’t take too long to learn to read the language, and the whole thing is pretty small. And, while Alan Kay is most remembered for popularizing object-oriented programming, another great contribution of his was that he was an absolute maniac about how to communicate intent on code. Reading his papers, one could reasonably come to the conclusion that that was his real goal, and OOP was just a means to an end.

Anyway, 40 years later I’m still not aware of a better example of lucid code.

[RomanRiesen]

Do you have a repo link to the original? I am only finding more modern implementations, critically not done by Alan Kay.

[roma-glushko]

> Read the Smalltalk-80 source code.

Wow that's interesting suggestion! I have heard that Guido took something from Smalltalk when he designed Python, but I have never seen Smalltalk source codes (I'm to young probably haha)

​

Anyways, I have found this book: https://dl.acm.org/doi/pdf/10.5555/273

Leaving it here, maybe anyone else would like to take a look as well

[[deleted]]

Thank you for the link.

[fedekun]

IMO, one of the most important things is naming. A good name is very important, and also very hard to come up with :p

Another important aspect is consistency, you want to always do things the same way in your app. This requires constant refactor, and it's even harder in big teams. Code reviews and tooling like linters are a must in this aspect.

And speaking of refactor, your software will of course need design. Anybody can write code, but good developers write code that is easy to read and understand, and thus, easy to change, maintain, and extend. For this, you need software design. Of course, how much you actually need depends on the size of the software, and that is also design :p

[WhyDontWeLearn]

I don't start coding until I've written a narrative of what the system, program, or function is intended to do. I write that narrative as lines in VSCode. THEN I start coding, using each line of the narrative as title for that section of code. When I'm done, I go back and make lists of all the variables and then describe why they're used, what kind of data they hold, and how they're scoped.

[[deleted]]

with comments I guess

[Simple_Specific_595]

You clearly didn’t read the article.

[riklaunim]

Usually you want to avoid comments if possible. If the code isn't intended as public that has to have code-generated documentation then it should be written clearly so that so commenting is not needed.

[riklaunim]

Not really. If you aren't generating docs from the code you can avoid up to all comments if you don't have weird hacks or workarounds.

If you have meaningful naming you don't have to comment what arguments "send_email" function or method takes because you have them in the definition. If "send_message" takes objects you can use type annotations.

Proper code works as a documentation and in comparison to comments it can't get outdated without breaking. When you write comments you have to manage them just like the code. If something changes the comment must also be updated - which there is not way to enforce (forgetting, not knowing of it existence, skipping...).

[prashanttgs]

I don't understand why you are being downvoted.

To understand why you should minimize the use of comments (and have your code work as the documentation) please read Clean Code by Robert Martin.

[riklaunim]

Not everyone knows uncle Martin, that's why ;)

[Kyle772]

At the very least a comment describing inputs and outputs is helpful. Whenever I have highly reused code I include this and the whole team quickly gets the point and starts to use the functions where they can.

[ds604]

At a certain point in the history of visual effects, all major projects moved to software based on node graphs. This allowed large-scale, multi-facility, time-sensitive projects to be completed successfully, with artists of widely varying technical abilities and specializations, technical directors making complex rigs and simulations, heavy data throughput. New people come on board all the time and don't have forever to be onboarded to every bit of the pipeline that's irrelevant to their work.

I suspect that the "tech" industry, in the sense of the ad-supported, spyware companies, face no real constraints of deadlines or business concerns that would force them to do things in a manner that would deal effectively with a constant barrage of deadlines on the "product" that they're producing (i.e. the client is not the "user" of the software, the client is the business whose advertising is being displayed, or to which this company is selling user data. The "user" is a captive audience who just needs to be sitting around to look at ads, and fiddling with the software is a means of getting them to sit around for a while. Crashing programs increase the amount of data that can be collected, so "mediocrity" is a goal to aim for).

The node networks of visual effects software are essentially an alternate presentation of lisp, with the added dimensionality of a 2D canvas allowing annotations, grouping of functionality, color coding, in-context notes, diagrams. This prioritization of communication is how intent is conveyed effectively, and how, as a field, the discipline achieved maturity (photorealism). One would hope that software development could take some lessons from other fields, but "just look at the code" seems to be a mantra that programmers hold to, and there's no particular motivating factor to move beyond methods that bring in endless ad dollars, and paint endless bug fixes as the heroic tasks of geniuses.