3 Ideas for Writing Clear Codes Past Coding Greatest Practices | by Kay Jan Wong | Jul, 2022

Write elegant, modular, comprehensible, and maintainable codes

You could have heard of the time period “messy code” and surprise what messy even means (when your code works anyway) or have come throughout some coding finest apply terminologies corresponding to SOLID design ideas, DRY (Don’t Repeat Your self), or KISS (Maintain It Easy Foolish) precept. There are such a lot of jargons and guidelines in coding finest practices that I discover it complicated and repetitive (irony from KISS and DRY ideas), and query if they’d work in apply since they’re in idea in spite of everything.

This text goals to supply a crash course and abstract of fine coding requirements, coding finest practices, completely different code smells, and design patterns, and ends off with 3 sensible suggestions for writing clear codes. In considered one of my earlier articles, I wrote about methods to select up new programming languages, this text is an extension to that since this text assumes some code understanding. Be at liberty to take a look at my earlier article,

1. Coding Requirements
2. Coding Greatest Practices
3. Code Smells
4. Design Patterns
5. Tip 1: Plan your parts
6. Tip 2: Repeatedly summary your code
7. Tip 3: Make use of open-source instruments

Coding requirements outline code conference or model information, like how English comply with grammar guidelines, writing codes that comply with coding conventions enhance the readability and understandability of the code.

Coding requirements usually comply with the identical guidelines throughout completely different programming languages however could differ barely since completely different languages have completely different syntax. There exists PEP 8 commonplace for Python, and code conventions created by Oracle for Java.

To maintain this text language-agnostic, coding requirements usually outline guidelines for

• Folder and file construction (for Java)
• Indentation and spacing
• Naming conference for bundle, module, class, variable names, and so on.
• Correct solution to carry out an import, write feedback and statements

Inside every class above, there might be loads of guidelines to comply with — there’s even a bit on ‘pet peeves’ inside PEP 8 documentation! With so many guidelines to comply with, it may be onerous to recollect or simple to overlook out on sure violations, just like having spelling errors in English.

There are instruments that assist flag out codes that don’t comply with correct coding requirements corresponding to IDE (Built-in Improvement Atmosphere) which underline codes that don’t comply with correct coding requirements or packages that assist reformat and rewrite codes, known as code linting. Among the common Python packages that assist with linting are pylint, black, and flake8, to call a couple of.

Coding finest practices outline idea and pointers to construction codes that improve modularity and maintainability of code

As talked about initially of the article, there’s loads of jargon used beneath the broad umbrella of coding finest practices. I summarized and drew hyperlinks between frequent terminologies within the diagram beneath. That is speculated to be a abstract, not meant to be exhaustively detailed with examples.

Following SOLID design ideas,

• Single Duty Precept: A category ought to have just one job
• Open Closed Precept: A category must be open for extension however closed for modification
• Liskov Substitution Precept: Objects in a program must be replaceable with cases of their subtypes with out altering the correctness of this system
• Interface Segregation Precept: A shopper ought to by no means be pressured to implement an interface that it doesn’t use
• Dependency Inversion Precept: Excessive-level module ought to rely upon high-level generalization, not on low-level element

Different design ideas and pointers embrace,

• Composing Objects Precept: Lessons ought to obtain code reuse by way of aggregation fairly than inheritance
• Regulation of Demeter / Precept of Least Data: Lessons ought to know and interface with as few different lessons as potential
• Abstraction: Simplify by exhibiting solely related info
• Encapsulation: Bundling attributes and behaviours into an object, and exposing options as crucial
• Decomposition: Breaking an entity into elements that may be applied individually
• Generalization: Factoring out frequent options of lessons that may be reused somewhere else
• Coupling and Cohesion: Loosely coupled modules are much less dependent and simpler to reuse, whereas excessive cohesion describes a module that has a transparent goal and isn’t extra complicated than it must be
• Inheritance: Attribute or behaviours that subclasses inherit from a superclass, or implement by way of an interface
• Info Hiding: Modules ought to solely have entry to info that it must do
• Separation of Considerations: Totally different considerations must be in several modules
• Don’t Repeat Your self: Cut back repetition of code
• Maintain It Easy Foolish: Simplicity must be a design purpose
• Conceptual Integrity: Create constant software program and make selections on how the system will probably be designed and applied

The primary takeaway is that these are loads of ideas, and a few ideas are contrasting! For example, encapsulation and decomposition have considerably reverse meanings, which results in the query of when must you use every precept?

In apply, we train these ideas wherever relevant, as much as our discretion, and we’d even go in opposition to sure ideas for a ‘better good’ on a case-by-case foundation. Figuring out these ideas is enough, and it shouldn’t be applied as a guidelines to fulfil every little thing.

Code odor is a symptom of dangerous code, that presumably signifies a deeper drawback

Just like coding finest practices, it’s enough to know of their existence, and never obligatory or potential to keep away from all code smells in code. It may also be onerous to keep away from code smells as they are often subjective primarily based on developer, programming language, and kind of drawback.

The extra frequent code smells are,

1. Feedback: It’s good to have annotations, but when feedback are overused (subjective) to compensate for the dearth of readability in code, it’s a drawback
2. Massive Class: If a category could be very massive (subjective), think about using decomposition
3. Information Class: If a category is just too small (subjective); reverse of a giant class
4. Information Clump: If a gaggle of codes incessantly seem collectively, think about using encapsulation
5. Duplicated Code: If the identical code, with little variations, is present in a number of elements of the codebase, think about using generalization
6. Lengthy Methodology: If a technique is massive (subjective), this means a poor separation of considerations, think about using decomposition
7. Lengthy Parameter Checklist: If a technique has an extended listing of parameters (subjective), contemplate passing parameter objects that encapsulate frequent parameters
8. Shotgun Surgical procedure: If a change in a single place results in modifications in a number of different elements, this means tight coupling

The objects above are a non-exhaustive listing of frequent code smells, the total listing of code smells might be discovered right here. As you possibly can observe from the listing above, code smells might be fairly subjective and tie in intently with coding finest practices — if you happen to apply and implement coding finest practices diligently, code smells may also be minimized.

Design patterns present options to frequent software program engineering issues, and are language and code-agnostic.

There are three kinds of design patterns — creational, structural, and behavioural design patterns.

• Creational design patterns outline methods to design strategies for object instantiation, corresponding to alternative ways to carry out inheritance or encapsulation, and so on. for instantiating objects
• Structural design patterns outline methods to design strategies for creating class and relationships, with a spotlight to maintain them versatile and environment friendly
• Behavioural design patterns outline methods to design behaviour of associated lessons, with a give attention to how lessons and objects talk with one another

Whereas design patterns are extra relevant to object-oriented programming, its design ideas are code-agnostic. Figuring out completely different design patterns allow you to pick out a design sample that’s extra relevant to the issue. The total listing of design patterns might be discovered right here.

“When you fail to plan, you propose to fail” — Benjamin Franklin

It’s good to at all times double-check the mission necessities and plan your parts to stop main code restructuring sooner or later.

Most often, on the level of writing code, you do have some concept of how the codebase goes to be structured. For example, a knowledge science workflow is structured into knowledge ingestion, knowledge processing, characteristic engineering, modeling, and analysis parts — and separate folder or information are created for every part as a part of the Separation of Considerations finest apply.

The parts might be derived from the character of the mission (on this case a knowledge science workflow) or might be a project-specific part. If the mission requires further parts to be added, corresponding to knowledge evaluation, plan for it and embrace them as early as potential.

Lastly, in addition to code-related parts, planning for data-related parts is necessary as nicely. Decide how a lot and what knowledge goes to be loaded and saved, and design how the info goes to be saved!

“Design is an iterative course of. One concept typically builds on one other” — Mark Parker

Following the earlier part, if you end up completed with all of the parts, the code works and nothing breaks — however would it not break sooner or later? There could also be altering or new necessities, knowledge, options, or implementation strategies.

Let’s assume the info path modified, and you find yourself altering a number of elements of your code to learn from the brand new path — this indicators a shotgun surgical procedure code odor. You carry out abstraction to summary out the info paths right into a configuration file, and the issue is solved.

The following day, the info format modified, and you find yourself altering a number of elements of your code to alter how the info is learn — this indicators a shotgun surgical procedure code odor. You carry out abstraction to summary out the codes into a brand new perform that masses the info, and the issue is solved.

This begins the query — Ought to you’ve got carried out the abstraction beforehand? Did you not plan your parts accurately the primary time? Nevertheless, if you happen to overly summary your code, this may result in pointless complexity as you over-engineered the code (which is one other code odor as nicely). That is the battle between coding finest practices in idea and in apply.

The final rule of thumb is to carry out separation of considerations and never hard-code variables. It’s okay if you happen to needed to summary out parts later throughout the course of the mission — modifications do occur and coding is an iterative cycle.

Don’t reinvent the wheel

Since each part is now separated, it’s simple to really feel desirous to need to implement each part from scratch. Implementing parts by hand provides the developer extra management over the move as nicely, as each half might be tweaked if wanted.

Nevertheless, the extra code you write and the extra intricacies within the codebase, the tougher it’s for different builders to grasp your codebase. If different builders don’t perceive your codebase, it makes it onerous to keep up sooner or later. It might be simpler to leverage open-source instruments which are extra broadly used and identified by different builders.

For example, in case you are scheduling your jobs, use Apache Airflow. When you’re performing experiments, observe your experiments with MLFlow. Leverage and combine open-source instruments into the mission as they’re typically higher developed and maintained by their very own builders and it might be one much less fear in your plate.

After refactoring and restructuring a number of codebases from my teammates, and likewise my very own codebase, these are a few of the suggestions that I discover helpful that will have saved me a lot effort and time. Coding is basically an iterative cycle and I nonetheless discover myself making tweaks and modifications even after following coding finest practices. Hope this text shed some mild on coding requirements, finest practices, code smells, and design patterns, and that the sensible suggestions could be one thing you comply with in your future tasks!

To recap, these are the three suggestions shared on this article

1. Plan your parts
2. Repeatedly summary your code
3. Make use of open-source instruments

Thanks for studying! When you appreciated this text, be at liberty to share it.