 Hello, once again welcome to the next new episode of the PHP Singapore podcast recording So with me today, we have on video chat Zion Eung and we also have on text chat Huirin Woo Because Huirin is using his laptop which has a faulty microphone. He can't really say as much But we can probably read his text on the screen So if you're watching the, if you're listening to the audio podcast We'll just read out his comments on our chat window And once we publish the video, you can also see what he say Right, Ken Hello everyone, so today we, let's look at the stories we have lined up for today So so far we have unfortunately So we only have one story so far, let me just bring it up Where is it? Chrome, you can just share the browser, yes I can share the browser And where is that story, I think it's Zion's Right, can you see this? Ah yes Let me just bring it over Okay cool, so this is, Zion had wrote an article recently And then it's about the three C's for coding About consistency, context, and continuity You want to share that? Okay, Zion here, this is probably going to be the shortest podcast So recently, there's a code review on a colleague's code It was kind of frustrated So usually I try to emphasize on code being maintainable So this is how it ran and it ended up becoming a blog post So today I'm going to share about three C's for coding Consistency, context, and continuity So about five years ago, I actually wrote a post It was titled 10% development, 90% maintainers So that was my view on software development and series today So basically, software development is 10% development, 90% maintainers 10% of the time, you probably spend let's say one month working on the project And probably you spend more than nine months maintaining it So for example, let's say Windows XP Windows XP was released in 2001 And it still accounts for more than 10% like a few, five years ago So that's more than 90% maintenance really So I was thinking of coming up with an easy and simple way To communicate my requirement for clean and maintainable code To work developers and to my colleagues in the business team So the first C, consistency So consistency basically maintains our focus mainly on coding styles and standards So if your code is written consistently And it is consistent, there are three structures You have a consistent way of naming the variables and the classes It makes life easier for everyone and you waste less time for each and every one So for each C, I will actually share three points So first point for C, consistency reduces cognitive friction It means you don't get brain freeze when you're looking at source code So supposing I say you have a newspaper in front of you And you're trying to read it, but there's a lot of grammatical and spelling mistakes No paragraphing, there's a lot of missing spaces, wrong punctuation And there's a mix of British and American English You'll probably be too hung up by the errors to focus on the article itself So in the article, I'll actually show a sample code A negative example of this in the grey box So in this case, you'll see a sample code The if statement So the first if statement has a space after the opening bracket But for the second if statement, there's no space after the opening bracket The first if statement uses the normal comparison The second if statement uses the yoda condition So value equals variable The first if statement does not enclose its code in braces So if you repeat a code, you might get a confused This console does not log 1 Does it actually belong to the first if statement or the second if statement The indentation is also not consistent So probably you'll be too hung up trying to figure out how to read this code And you waste actually a lot of time Second suck point Consistency allows easier search and replace For example, if you're consistently naming variables using camel case And let's say I don't look for something related to person ID So I'll just look for small letter person Capital ID, person ID And not variations like person underscore ID Capital person ID Person in small letters ID in capital letter or with a higher Or even try to come up with a regular expression pattern to do the searching So this is for searching Replacing will be another beast The third suck point Consistency helps to reduce guesswork When modifying editing code So for the sample API response below in the JSON format So you see if I want to name a new key related to person ID So what will I name a new key? So if you look at the sample API response The key got used camel case Snake case Pascal case Cobalt case Caps case And some funny case So in this case Then you're going to call the developer Searching how one case do I use Waste of time Now come to the second C Which is context Now Code Source code will tell you the how But context will tell you the why So she will say what's the background story What's the rationale behind this code So it helps other people to understand the rationale behind So for example let's say you onboard a new developer It come in This slide of code is actually redundant I think So I delete it But it turns out that it affects some obscure logic Spread across 10 other files in 5 different folders So for this second C context Again I have 3 sub points Consistency right 3 sub points First sub point Contacts can be preserved via dot blocks So dot blocks are basically Especially for meta commands They use annotations to document specific Samples of codes Typically available functions and classes So for example for JavaScript There's gs.phpusers.phpdocument. Sometimes you can use api. for documenting REST APIs So in this grey color box That you see in the middle of the screen right now There are 2 functions The first function has no dot block No documentation block It's just called function z And it takes in 2 meta parameters called q and r So imagine let's say the function has 1000 lines Imagine reading 1000 lines to try to understand What the function does Imagine doing this every time You come back with this piece of code Because you can't remember what you understood 3 months ago when you read this piece of code Now we come to the second function below It's called compute height Good name Name that gives a context It has a properly named method parameters We may expect we will show And there's a dot block, a documentation block So as I made This function compute a height based on spread ratio It takes in 2 parameters First parameter is a float Second parameter is a float And it returns a float So simple, short and sweet You don't need to read through 1000 lines You can just go What does this function does Based on the dot block itself So you can save an hours of time Second sub point Contacts can be preserved by commands So dot blocks are not made Just document a summary of a variable function of class But commands can be sprinkled everywhere So as I said just now When a developer looks at the source code He understands the what and how How this is being done How to calculate prime numbers But commands will tell you why The rationale The logic behind this for loop Or say that this piece of code is linked to a GR issue This is to solve a certain bug There's a certain edge change to this is solving So in this piece of code The gray box in the middle of the screen Is basically You see two comments Jira, ticket 1, 2, 3 This event listener will keep full screen change Is to cater for Mac OS Safari Because webkit and full screen doesn't work And then you must add The listener on the video element itself Not the document Whereas for a normal full screen change You need to add the listener on the document itself So two lines of comments So don't always assume that The developer looking at this Is an expert on full screen So instead of wasting time To look at the Mozilla docs So these two comments Save time Now For where I can stop talking in Chinese After drinking this Okay First point Contacts can be preserved by documentation When I say documentation I'm not talking about Microsoft Word files Or Google Doc files Or GitHub Wikis or PDF Because all these things Installation or special You need to install Microsoft Word To read a whole document You probably need a Google Drive account A Gmail account to read the Google Docs And when the person leaves the company They will normally suspend Or delete their person's account So the creator Who originally created the documentation Has left the company And because the company suspends the account You lose the access to the document forever When they are stored separately from the code So for example GitHub Wikis So suppose one day I moved to a big bucket of Gillab What happens to the wiki Will someone actually remember To port everything over Most of the time actually no So when I say documentation I'm referring to plain text files Written in month down format They are committed to the source code In the same repository Wherever the repository goes Wherever the source code goes The month down files will go together with it And because it's text based So you can just view it Or edit it using a normal text editor And you can actually try to change Just in the document as well I can just test also in line By keeping your document or comments As close to the code itself I think that's acceptable Correct So the examples would be The standard readme and the change log .md open source projects So over here there's a sample readme Submit, how to install How do you deploy Now sometimes We take things for granted I see a lot of projects Where they don't have a readme And even if you have a readme They don't have an installation section Now you may say that it's a Fryhand project So I see what package.json Automatically I just run mpn install But there may be certain caveats So usually in my readme I will have an installation section Deployment also Some people say Using CI The Travis CI demo file Is already in the report But it always helps to Explain plain English Okay Project is deployed via Bitpocket pipeline The files are uploaded to S3 And serve via cloud front And then Normally after upload They will actually Clear the cache You need to set certain response headers All these are not done In the CI file These are not being done once And forget about it For example if you switch Your CDM provider Or SAX3 You need to set that from scratch So who will actually remember All these caveats say You must set cache aspiring to one hour You must set Cost policy So normally I will actually have this In my deployment Session Workflow Previously I came across this project This video project It took me 3 days to look through The whole code Just to get a sense of how the general workflow works Like the literal and the single file So over here in the readme For my readme I normally have a workflow How the code Goes from end to end Same for the clients Your browser all the way to the back end And all the way back The rough workflow Now we come to the third C Which is the last C Continuity So continuity Aims to make handovers Most move Easier and complete So Continuity largely involves Parting of institutional Knowledge There's only so much that you can Tell someone In the one hour handover session This also trickles down When you have code That has a poorly designed Architecture or overly Completed workflow For example, I said the previous project I was talking about This one called this one That's a special one on top of this one Just to make it work nice with typescript and everything In the end it will be 3 days You will actually try to understand the simple How the simple workflow of the project So For example, let's say like When was the last time you saw an iPad shift Instruction manual? Actually you don't have Because you try to make it simple It has a simple enough user interface Of course some video advertisements will help So Make it so simple that When people look at it They can easily trace The workflow and the architecture So we remember the keys principle Keep it simple and stupid So continuity Also has 3 sub points Because Consistency First sub point Continuity First Increasing the bus factor The bus factor Refers to the number The minimum number of developers working on a project That will get knocked down By a bus Yes, your bus As in your public transport Before the project comes to a complete hot If the project has a bus factor of 1 All of the main knowledge Is stored in a single The The The The The Second sub Point Can you hear me? Just a chat Can you hear me? Can you hear me? Ok Second sub point Continuity involves humans in the process So unlike our grandparents era, their employees nowadays seldom work for a company for life. When I say life, I mean decades. And that is even if the company can last a long. So for example, like my mom, she worked for this logistic company for 17 years, one-seven. So like normally now, these are after three to five years, or you get a long service awarding. So even if you stay at the same company for many years, you may not be assigned to a project for life either. So simply put, not many of us will have the luxury of working down the corridor and ask a big developer on this piece of code. Hey uncle, you wrote this piece of code 50 years ago. Can you help me explain this part? We don't have the luxury anymore. Now I come from British countries, they are asking for cobalt developers because they are having the influence of requests and their main place running cobalt. So where are the cobalt developers? I don't know. They are the original one. Last point, the third sub point of continuity involves professionalism. So this one cuts across all tricks. You see the road sweeper, right? Whether raining or shining or there's a haze, she will diligently sweep the road. And then the hawker, two more hours every hour we take away, right? She will cook every plate of food to adjust standards. You will say like, now let's customer, I just bring less effort, I need help put. No. Our proper hawker with professionalism, with a professional attitude, will always cook each plate properly to adjust standards. Then come to the hotel. Let's say that the front desk manager, this customer can slap him for no round reason to van his anger. The front desk manager still serve him with a smile. So that is called professionalism. So basically we are paid by our company to do our job. Even if we have our own company, we are being paid by our clients. So it beholds us therefore to do our level best despite emotions and to ensure that our code can be easily maintained even after we have left the company. So don't want the bridge always live from good terms. So that covers all the three things, consistency, context and continuity. And frankly speaking, actually all these are tied in bound by a common D discipline. Because frankly speaking, if you don't have discipline, it's a bit hard to actually do all this. But there will be another topic for another day. Yeah, that's all. Thank you. Sure, that sounds really cool. Thanks. So I think a couple of comments. I think this equipment actually shared some things. The one he shared that I think he's targeting the first part about being about consistency. So in the sense of consistency, you could actually use something like instead of enforcing it in terms of talking about it and whatnot, you have a system in place to help introduce some of this discipline, right? So some of the disciplines that you talk about. So instead of having making it a human factor, you make it more of like the system will take care of it. So basically you introduce some things like JSON API, for example. There's one way of like introducing some form of like syntax for JSON. He also talked about another thing called hell, which is also a way of like sanitizing how things should talk to each other. So I think it's basically hypermedia. Hypermedia and hypermedia to do that. And then the last one, so other than using these two techniques, I also recommend something like PHP lint, which is probably kind of close to JS lint and a JS hint, which is kind of like a way of like having some system in place that will help you clean up your code or even warn you of like badly formatted code. So in the sense that you want to enforce a certain PSR formatting standard, you could use something like this. Instead of like making it like, oh, you know, instead of chalk to actually format it correctly, you make it part of your workflow. Once you become part of the workflow as a natural consequence to what your daily workflow is, then it wouldn't be so much of a chore, right? Because enforcing consistency and all that stuff can be a bit of a hassle. On the second C, I think he also talked about context. I think we also talked about this thing called function length, I think. Was this related to the function length? Or was the function length related to this one? I can't remember. Yeah, they've always said that if it's too long, it probably is a bit hard to read through. Yeah, I think if Martin Fowler has read a lot of articles in respect to all these things, or like how to write good code and all that stuff. And yeah, having contacts like this, introducing contacts using documents. Long methods are usually not a good thing to have anyway. This is Ruby developer called Sandy Metz. She also had this thing called five rules. She has a couple of rules that she set up, right? So maybe we can share with you Sandy Metz rules. So it's kind of an interesting series of rules for developers. So we also tried something like this. And number one is classes are no longer than 100 lines of code, methods are no longer than five lines of code. Pass no more than four parameters into a method, hash as in associative array, as options are also parameters. So just be mindful. I think in this case, she was talking about controllers, as in controllers can initialize instantially only one object. Therefore, views can only know about one instance variable, and views should only. So it's kind of in the context of MVC framework, where you pass something from controller into the view, make it just one object, and then have somehow. So she kind of wrote down this couple of rules as a way of like, because she was working with a team, and the team was also very consistent and very like, they wrote very long functions and all that stuff and a lot of very consistent way of doing things. So she kind of like put her feet down and say, Hey, let's try this. Now, so in this way, it kind of forces them to think about smaller functions, smaller code, smaller classes, so that it's easier to understand and easier to recognize. So it's also one way you can think about it, having rules and everything. In context, well, I will comment about context. Commence is a very, not a very good way of documenting things, if it's important enough. So it's like, my view is that it commences, once you see too many of it, you become like, white noise, you don't really care about that anymore. If there's too much comments, you don't really care about that. Although having a dog block like this, of course, is helpful for your IDE to work, to hint things. So this is kind of like writing code here anyway. But for comments like this, I mean, it's okay. Yeah, so I think if you flip it around and say, you have no comments in your code, and when a comment appears, it becomes a bit more like, oh, wow, there's a comment here right now, but be careful what it's all about. Because if you're too liberal with your commenting, it becomes, people just bypass it or don't look at it. So when you don't use comments, you got to think of other ways of doing it, which is, for example, writing more, giving your functions a bit more helpful or easy to understand names. That's one way, naming your variables better, even organizing a code in a way that it would actually read your functions and the components and all those things you're passing read like, introduce or rather it kind of tells you the intent when you look at the function of the name of the function, the variables that pass it, arguments that pass it, all this kind of tells you an intent. And the intent is obvious by looking at how the function names and the variables, arguments are called. So there's one of the ways, I think that's where naming things well is very important, so that it's easier to, so you don't, instead using comments to tell you the intent, you use your functions to surface intent, right? So it's another way of doing it. And of course documentation at least is very invaluable. And even like, for example, for deployment, and we even go as far as saying, hey, you should probably use infrared code or even some form of deployment code, right? So in some in the project, in a talk I saw recently, which they talk about how to reduce complexity in terms of like microservices. So what they do is that all the local microservices have a common make file. So all of them have make files. And in the make file, you can just make build or make deploy or whatever. So basically there's a standard syntax, they use make something, make build means you're building the binary, make deploy means you're actually deploying the binary, right? So across all your microservices, you have the same syntax and it actually makes it a lot easier when you context switch between different microservices. But I guess it's a microservice architecture, but you, because it will be relevant. You will have, you will have many projects in your, in your, in your infrastructure, like legacy code, new code and whatever. So all these are separate smaller monoliths. Yes, my cat is calling me. I'm sorry. My cat is outside. It's trying to get in. Sorry. So anyway, so yeah, long function. So yeah, so having the infrastructure as code goes to be aware of like just reducing the amount of documentation you need to have. We also mentioned something about user plus one on Linters. So Linters are also good. Too long, too long methods, you will just ignore for those who are inherited interested in using. So for those who are interested in using JSON API for Laravel, there's also a, he says I've been using it for a year. So he's using this library called Laravel JSON API. So if you're interested in using Laravel JSON API in Laravel, there's actually a library for that. Okay, interesting. Unfortunately, you don't have a query and can't be, you don't have any voice right now. So you can't hear him. But yes, my cat has a voice. So I don't know. Okay, fine. Let me just let the cat in. Sorry. Hello. Okay, I'm back. Anyway, yeah, thanks. It's a very interesting article. And how, what do you publish this? Just a few days ago, is it? What was it last? 24? Okay, cool. Still quite recent. Because one, two weeks ago, so also one thing I find that a lot of times when I see handovers, then you'll do a last mini documentation near to one month before they leave. Where else, these are things like documentation should be done like big rugby so that it's not like one whole shot. Because after some time, you forget like, hey, actually how is this thing deployed? Things like that. Yeah, talking about documentation, there's also this some other thing, one of the things that we like to use is called lightweight ADR. Okay, ADR stands for Architecture Decision Record. So lightweight ADR. So you will find this being talked about in the ThoughtWorks Technology Radar. So if you are not familiar with it, the ThoughtWorks Tech Radar is actually kind of like a quarterly magazine that ThoughtWorks publish where they give an overview of like, what are the different technologies that you should look out for, upcoming stuff and all that. So lightweight ADR was something that they talked about in one of their technology radar like some years ago. And they have written it down as this something you should adopt. So it is very interesting. So basically, lightweight ADR is basically, ADR is actually a decision record. So you could use a markdown file, which whenever you come to a decision about some technology stack or whatever, right? Then you could use ADR to kind of document this is why we're doing it. And this is the context in which it makes sense to use it. Yeah. So yeah, this is so well those ways that you can use. There's also a ADR command line tool. So ADR command line tool basically lets you ADR tools. So let's you create using a command line to create like markdown records in your repository. So like in ADR init, like something like this, then you say ADR I were implementing some new stuff. And then it will tell you then you can basically go inside there. So it creates a markdown file, which is a certain format. So it's kind of interesting. And it links to actually links to Michael Nygaard's article on this subject. So Michael Nygaard is a quite a prolific author in this area. And then he wrote an article about this as well, documenting architecture decisions. So it's actually one of the ways that you can, it's a lightweight way of like, I'm also practicing this in my company right now. So as in whenever they come with a decision, whenever they come up with a decision about some technology to use or why we write our code a certain way, we just make sure we write a new document about it. It's taking a while to load this document. Anyway, yeah, but this is one of the cool things in the industry. So you check it out. Cool. Cool. Cool. Anything else? Anything else from here? Anything else to share? Cool. Yeah, so he will share a bit more about this, about new things in his next podcast. So right here. Okay, cool. Can can. So yeah, from all of us here at PHP, Singapore podcast, that's we're in and Zion and myself. That's all we have. Anything, any new updates or changes on your end, Zion? Not really. Yeah, just got a new VP engineering and a new prior developer on our side. Cool. Nice, nice. So on my side, I've just started working from home. As you can see, I'm at home now with my cat over here. And then. Sure. It's not very happy doing this. Okay. Okay. Drive down everywhere is probably gonna take his exam soon. So online, online exam, huh? Even though there's been an announcement that media exams in Singapore are kind of cancelled being in lieu of COVID, because of COVID-19. So, but he said he has to take his exams online. So unfortunately for you, come size ma like that. Must work hard. Okay. Go hard. Don't play so much. Can. Cool. So that's that's all we have for this month's podcast. So hope to see you all again next year, next month. And we can chat more. All right. Cool. Bye. Okay. See ya.