Forem: Saifur Rehman Khan

Clean Code - Part 1

Saifur Rehman Khan — Sun, 24 Nov 2024 04:36:36 +0000

This is a 6-part series article on Clean Code. I used (YT) video from Robert C. Martin aka Uncle Bob as a reference. If you want to deep dive in each topic discussed here, please refer to the video and/or the book 'Clean Code by Robert C. Martin'.

Now let's get started.

Why should you care about Clean Code?

Clean code acts like a well-defined communication protocol when you are working on a project along with your teammates or on an open source project. You want to write code which is not just understandable by a machine but also by your fellow programmers. A computer can understand 10k lines of code(if written syntactically correct) even if you put it in a single line with no spaces but I bet your peers will have a hard time understanding it. Clean code makes debugging, reading codes(which you will be doing more than writing in Software Engineering), perhaps teaching?, etc a lot easier and more efficient.

What is Clean Code anyway?

Programs which is simple, direct, elegant and efficient. Clean code does only one thing and does it well. No surprises i.e when you are reading it, it should only do what you are expecting. It should look like well-written prose and by someone who cares.

Rules of function

A function should be small typically from 4 to 20 lines. It must do only one thing. How do you know if a function is doing more than one thing? If you see a function and you can extract another one from it, the original function is doing more than one thing. You should keep extracting functions from one another until it stops making sense to extract any further. Each function should have a proper name and it should be a part of appropriate classes(functional programming?) and modules.

However having a hard requirement of a function of line between 4 to 20 can be difficult because sometimes a function which is doing only one thing could grow more than 20lines. Additionally, if you are on a line of code which is result of call of 10 different small functions, it will be hard to backtrack when you are debugging or trying to understand it. so, keep it balanced and try to follow the "One function - One job rule" more strictly rather than "length of code rule".

Function arguments/parameters

How many arguments function should take?

A function should not take more than 3 arguments(Soft rule). Anything more than three should be an object.

Passing a Boolean to functions should be avoided if possible. Why?

Because when you are passing a boolean to function, most likely there will be a if/else statement in that function and code in the if/else block could be extracted out as two different functions.

Avoid `switch` statements

switch statements are great for small, finite and well-defined sets cases eg parsing commands or options but they can become a painful dependency management problem if you are calling different modules in your switch statements.

Lets understand this with an example, Shapes.
We have shapes like triangle, rectangle, square, circle, etc. We want to perform some actions based on shapes like rotate, draw, stretch, get number of sides, etc. If we have bunch of switch statements floating around for each actions, what will happen if we want to add new shape? Exactly, find all the switch statements and add actions for this new shape. And what will happen if we want to add an action which can be only true if two or more conditions satisfy? Also what does rotate or number of sides means in case of Circle? You see the problem. For such cases, Polymorphism works best as it follows Open-Closed rule.

Open-Closed Principle - Software entities (such as classes, modules, and functions) should be open for extension but closed for modification.

No Side-effects

A side effect in programming is any change a function makes outside of returning a result, such as modifying a variable, updating a file, printing to the console, or interacting with the outside world.

Some example of side-effect functions can be open() and new in C++. These side-effect functions comes in pair like open/close, new/delete, acquire/release, etc.

Does that mean we should not use these functions? Ofcourse you are going to use them if you write in C/C++ but the important point here is to make sure you handle them properly. That's why some programming languages comes with Garbage collection to avoid memory leaks but still you need to manage a lot of things by hand for most of the cases.

But side-effects are not only limited to language's built-in methods/functions, we can very easily introduce them and suffer while debugging or when trying to understand someone else's code. For eg, our int userId might very easily insert a user id in database and return it. How to avoid it? Ans: Command and Query Separation.

Command and Query Separation (CQS) is a software design principle which states that a method (or function) should either perform an action (a command) or return data (a query), but not both.

Okay that's that but what can you do to enforce proper resource/transaction management like reading from a file and closing it, connecting to a database and closing the connection, serving a request which can change two or more states, etc? Ans: Exception handling
You can have a finally block which will release the resouce or can do cleanup for you if you don't want a partial completion of the request and so on. But avoid having bunch of code before the try block and code after except/finally block. The function/method which has this exception handling logic should only call functions/methods which can throw. Also, Never ever use nested try/catch blocks.

DRY

Don't Repeat Yourself

Pretty self-explanatory ig? Just try to avoid having repeated code all over the place. Move repeated codes in functions(pass arguments if needed) and modules.

Test your code

How would you know if the code you wrote is not going to break? Well, I tested the the feature and it works.

But what if it breaks or behave differently on different sets of arguments/situations? What if a simple arithmetic operation can overflow if correct datatype is not choosen or you got more strings in your fixed sized string array? The small or big changes/additions to the software can break the system or can be a bottleneck in the pipeline and you might have to wake up at 3am to fix it or backout and can impact clients.

To avoid these kind of situations, we write tests to test our code before shipping it to clients. There are many types of tests such as unit, integration, system, A/B, etc. Although more coverage means more confidence in your code, having unittests and integration is more common you will see in most of the codebases. So, try to write good, robust and good coverage tests.

--
That's it for this article. Lmk if something is incorrect or missing. Thank you.

Representing and Manipulating Information in modern computer - Part 2

Saifur Rehman Khan — Thu, 21 Nov 2024 01:16:00 +0000

Link to Part 1

Addressing and Byte ordering

A 4-byte int in a 32-bit machine stores all its 4 bytes in contigous sequence of bytes. It can be store in two way namely Little endian and Big endian depending on machine. Not going much into details a Little endian stores an int(4bytes on 32-bit) of hexadeciaml value 0x01234567 something like following(assuming starting address is 0x100):
Addresses/Values
0x100 67
0x101 45
0x102 23
0x103 01
and similary a Big endian will look like following:
Addresses/Values
0x100 01
0x101 23
0x102 45
0x103 67
I hope you can see the difference in the ordering. Linux 32bit, Windows, Linux 64bit follows Little endian whereas SunOS/SPARC follows Big endian.

This is important because when sending a message over a network from Little endian byte ordering machine to Big endian byte ordering machines and vice-versa could be an issue. Most of the programmers don't find it is an issue because networking applications are written in a way which does this convertions for us but if you are writting an network application, you might need to consider this.

Integer Arithmetic

You might be surpised to know, adding two positive number can result in a negative number and x < y can give you different result then x - y < 0.

Let me give you an example, lets say we have a computer which stores an int as 4-bit and we have two unsigned int x and y.

unsigned int x = 10; // binary rep: 1010
unsigned int y = 15; // binary rep: 1111
unsigned int z = x + y; // ???

The value of z is 25. right? right?

Well no. If you convert 25 into its binary representation, it comes out to be 11001 but as I mentioned our computer can only store 4-bit integers(values from 0-15 incase of unsigned). So, what will our computer do with the extra 1-bit? You are right, it will drop the higher-order bit(first bit from left) and we will get 1001 which converts to 9. This is same as doing module with 16 ie 25 mod 16=9. This behavior of computer not limited to arthmetic is also called Overflow.

But why I'm using unsigned int here? Will this addition behave differently with signed integers?

Answer: Yes but before explaining what will the result and how our computer ended up with that, lets first understand how signed and unsigned is different with our 4-bit size integer.

signed integers

They can store positive and negative both numbers values from -8(bin rep: 1000) to 7(bin rep: 0111). The higher-order bit(first bit from left) is the one which gives signed integer negative values and rest of the bits yields in positive. So, to get smallest number we need to flip higher-order to 1 and other bits 0 and to get largest number we need to flip higher-order bit to 0 and other bits to 1.

unsigned integers

They can only store positive numbers values from 0(binary rep: 0000) to 15(bin rep: 1111).

Now, because x=10 and y=15 will overflow before addition, we will use something smaller:
int x = 5; // 0101
int y = 6; // 0110
int z = x + y // ???

The binary representation should be 1011 if we ignore signed consideration. As you can see, the higher-order bit is flipped to 1 and from above, the value of z will be -5(= -1*2ˆ3 + 2ˆ1 + 2ˆ0) instead of 11.

and also, adding two negative can result in postivie. eg,
int x = -8 // 1000
int y = -5 // 0101
int z = x + y // ???

Now z will be -13 which is 10011 in binary(the higher-order bit is for negatives ie -1*2ˆ4 = -16) but our computer can only store 4-bits so it will drop higher-order bit and become 0011 which is 3 in decimal. Again, overflow.

This is why x < y could result differently from x - y < 0 if we does not handle arthmetic overflows properly. As a programmer, we should always pay attention while choosing datatypes by considering their capacties and behavior in different situations as they might become result of hours of debugging.

That's all for today. Please comment out if some information here is wrong or is missing. Thank you.

Representing and Manipulating Information in modern computer - Part 1

Saifur Rehman Khan — Mon, 28 Oct 2024 00:37:56 +0000

As most of you might already know computer can only understand, store and process on a bit(0 and 1).

But why?
Well it turns out, two-valued signals can readily be represented, stored, and transmitted easily and more reliably than traditional base 10 number representation — for example, as the presence or absence of a hole in a punched card, as a high or low voltage on a wire, or as a magnetic domain oriented clockwise or counterclockwise, etc.

Morever, a single bit is usually not very helpful in representing anything meaningful in computer but once we combine a sequence of bits, we can represent any finite set. for example, we can encode bits into negative/nonnegative and floating numbers and also can encode the letters and symbols in a document. This is why(or maybe not) we use 8bits or a byte as the smallest addressable unit of memory. In binary notation, its value ranges from 00000000 to 11111111. When viewed as a decimal integer, its value ranges from 0 to 255 and in hexadecimal it ranges from 00 to FF. We usually write bit patterns as hexadecimals(0 - 9, A - F) because it is easy for us to convert to/from binary notations.

In C programming language, numeric constants starting with 0x or 0X are interpreted as being in hexadecimal. The characters ‘A’ through ‘F’ may be written in either upper - or lowercase. For example, we could write the number FA1D37B as 0xFA1D37B, as 0xfa1d37b, or even mixing upper - and lower case (e.g., 0xFa1D37b).

Okay lets cover one more thing,

Data sizes

Some CS terms ahead!!!

Virtual memory - A conceptual large array of bytes in memory(there is more to it but it will come later in the series)
Memory Address - A unique number used to identify a byte of memory.
Virtual memory space - The set of all possible memory addresses(more will come later).
Word size - The nominal size of pointer data or maximum size of virtual memory address.

Today's computers are of either 32-bit or 64-bit word size which means programs can have access a range from 0 to 2^32 - 1(incase of 32-bit) and 0 to 2^64 - 1(incase of 64-bit) of virtual addresses. Most of the programs compiled in 32-bit machines can be run on 64-bit machines as well but vice-versa is not true.

Computers and compilers support multiple data formats using different ways to encode data, such as integers and floating point, as well as different lengths. For example, many machines have instructions for manipulating single bytes, as well as integers represented as 2-, 4-, and 8-byte quantities. They also support floating-point numbers represented as 4- and 8-byte quantities. The exact numbers of bytes for some data types depends on how the program is compiled. I showed sizes for typical 32-bit and 64-bit programs below:

To avoid confusion between bitness of the machine and compiler settings, ISO C99 introduced some datatypes where datasizes are fixed regardless of compiler or machine settings. As you can see in the above screenshot, int32_t and int64_t are among thems. Using fixed-size integer types is the best way for programmers to have close control over data representations.

Before signing off - We should try to write code which can be portable to different machines and compilers. One aspect of portability is to make the program insensitive to the exact sizes of the different data types. With the transition to 64-bit machines, many hidden word size dependencies have arisen as bugs in migrating 32-bit programs to new machines. For example, many programmers historically assumed that an object declared as type int could be used to store a pointer. This works fine for most 32-bit programs, but it leads to problems for 64-bit programs because as discussed above the word size or pointer size of 32-bit and 64-bit machine will be different.

Okay. that's all for today. Thank you.

Ref: Computer Systems: A Programmer's perspective.

someone told me to write as I learn

Saifur Rehman Khan — Sat, 26 Oct 2024 00:30:02 +0000

Hello world!

so this is my first attempt to write a technical blog as recently I started two very interesting book and someone who I know who definitely has more technical knowledge told me to write about whatever you learn even no one reads it. It makes sense to me as well. Maybe I will be more consistent in my learning and maybe I will trying to understand better because I will have to explain it to the world.

Okay now let me mention few things regarding this series of blogs:

I'm starting two books: "Computer Systems: A Programmer's persective"(A book discuss different aspect of a computer from software to hardware to networking) and "Composing Programs"(focuses on methods for abstraction, programming paradigms, and techniques for managing the complexity of large programs)
I will try to write atleast one blog each week but i cannot promise if it will be consistent.
I might stop reading a book for some time(if i get bored) and start reading some other(and write about it) and comeback to above two again.

Before siging off, here is one interesting thing I learned today in "Computer Systems: A Programmer's persective" book about improving performance of a system:

Amdahl's law
is a formula used to find the maximum improvement of a system when only a part of it is improved.

The law is expressed as: S = 1 /((1 - P) + P / N)
Where:
S is the speedup of the system.
P is the proportion of the program that can be improved.
N is the number of processors.

If you throw some number to above formula, you would notice that even though we made a substantial improvement to a major part of the system, our net speedup was significantly less than the speedup for the one part.
This is the major insight of Amdahl's law — to significantly speed up the entire system, we must improve the speed of a very large fraction of the overall system.

Okay. That's all for today. Thank you