Forem: Grzegorz Ziemonski

Simple Names

Grzegorz Ziemonski — Fri, 20 Sep 2019 22:24:00 +0000

Photo by Samuel Zeller on Unsplash

I have a feeling that even when we try to use nice, descriptive names in our code, we still tend to make things too complicated. For some reason, we use this "heavy", technical vocabulary instead of plain, simple words that we would use in a conversation with non-tech people. Yes, it looks very smart and it is clear when we write it but it gets confusing over time when we have less contact with that part of the code.

I started thinking about this a lot when working on a new feature recently at work. The details are irrelevant to the idea itself, but a couple of examples might help illustrate what I mean.

At one point when using the application, the user was supposed to enter a special code in a bunch of inputs and had limited time to do so.

We needed to make sure the final "submit" button cannot be clicked until the entire code has been entered i.e. all the inputs are not empty and we had to give a name to the button-disabling condition. For whatever reason, my brain was suggesting stuff like notAllInputsFilled, invalidCodeLength, or shouldDisableSubmit. All inputs? What "invalid" means? Disable when should disable? Really? It took quite a while to settle with codeTooShort.

A while later we needed to add another condition to disable the button - the user has run out of time. Again, for whatever reason, it took us a long time to come up with "obvious" ranOutOfTime. Before we came up with it, a whirlwind of expiredCodes, expiredTokens, pastExpirationTimes, and other weird stuff came through my mind. Heh.

Struggles like this kept popping, again and again, just to implement one very simple feature. Thinking about all the codebases I've seen over the years, I think it's not just me - it's a wider problem. Of course, effective communication is always hard and code is no exception. Yet we seem so used to the technical jargon that we sometimes forget to communicate (through code) like normal human beings.

One or two names like in the "bad" examples above will not make or break a project but it stacks up. Even in a small project, we probably have hundreds of names and not all projects are small. Over time, we can't just read the code anymore, we have to "decode" it, even though we understand every single word in every single name.

So here's my little tip/wish: let's use simpler, more conversational, more human vocabulary when naming things. We'll thank ourselves sooner than we think and maybe others will too!

Push for a Deeper Understanding

Grzegorz Ziemonski — Tue, 12 Feb 2019 10:37:17 +0000

Some time ago I had a weird conversation with one of my university colleagues. He was struggling to get some basic stuff working in Angular and he asked me for help. It went something like this:

Him: Do you know why this might be not working?
Me: Oh, yeah, you're calling stuff in the wrong order. Move this here and move this there.
... sounds of coding ...
Him: Yeah, works now, thanks!
Me: No problem, it's how the bootstrapping works. See, when Angular...
Him: I don't care how Angular bootstrapping works. I want to build an app, not learn Angular implementation details.
Me: Meh.

Sounds familiar? I had at least a dozen conversation of this kind throughout my career so far.

The problem at hand, if that's not obvious yet, is that oftentimes we are so focused on solving the problem at hand, that we forget to ask one of the most important questions: why?

One consequence of that is pretty straightforward - the next time we come across a similar problem, we will hit the wall again and have to solve it all over again. In the "best" case scenario, the new problem will be similar enough to the old one and we will be able to copy the solution that we found before.

The other consequence is a little more profound. Every time we forget (or consciously reject) to push for a deeper understanding, we strip ourselves of a little bit of growth. Instead of learning something and being a tiny bit better programmer, we are merely a tiny bit older one.

For a singled out case, the overall difference might be marginal and barely noticeable. Over time though, the small wins (or their lack) compound and the difference is substantial.

Therefore, here's my advice which you have already figured out by now: When you solve a problem, ask yourself: why does this solution work? What is the underlying principle that will allow me not to face this problem again?

Have a great day!

Weapons of Math Destruction

Grzegorz Ziemonski — Thu, 07 Feb 2019 14:53:46 +0000

I've recently read a book titled Weapons of Math Destruction and I think it conveys a message that's worth spreading further.

Long story short, math and algorithms are having more and more influence on our lives, and some of these "things" really deserve a WMD title - they hurt thousands of people, whether by taking their money, keeping them in prison, or unfairly taking away their chances of better education and/or a better live in general.

In a sense, this book is a call-to-action for us developers. We need to make sure that the algorithms that we're developing are well designed and well tested, including the all important feedback regarding it's results. It's also a call to push for better control over algorithms, especially in the most important areas of our life. The burden of proof that an algorithm works should lay on the creator, not on the person affected by it.

It's not the easiest read, or at least it wasn't for me. I felt a constant mix of "this is a good read" and "oh, that's disgusting" as I learned about more and more damage caused by algorithms that were supposed to be objective and fair.

If the topics I mentioned seemed concerning to you or you believe that algorithms that rule our lives are statistically sound, unbiased, and fair, I highly recommend picking up the book.

If there's somebody that has already read the book or knows some other good sources on the topic, I'll be glad to read about it in the comments.

Have a wonderful day!

Contributing vs Dumping

Grzegorz Ziemonski — Mon, 28 Jan 2019 12:43:54 +0000

One of the things that have drawn me to DEV was that it mostly consists of individuals willing to share their experience, knowledge, and discuss things.

That's in contrast to some other sites that became a dump for companies willing to advertise themselves or their products with low-quality, para-technical content.

Sadly, my today's DEV experience shows some room for improvement in this area:

This is not meant to be an attack on Octoparse or anyone else. I'd just like to feel that all members are at least trying to contribute to the community, not just using it as a means to another end.

If I'm being too harsh or shouldn't sweat over an isolated case, let me know and I'm sorry in advance!

Retrospective Antipatterns

Grzegorz Ziemonski — Wed, 09 Jan 2019 12:22:51 +0000

Hey! Hey! You! Yes, you. Come here. Let's have a little talk.

Just to be clear, we're not here because you're the guilty one or anything. (The real reason we're talking is that I started a very long data extraction on my machine and I'm bored waiting 'till it's over.)

So... I've been to some of your retrospectives lately and I'm kind of disappointed, you know? It's like... you guys are so clever, there's so much potential. And still, there's a few things that drive me crazy...

First of all, the moaning.

I get it. After X weeks of hard work, you finally get a chance to air your frustrations and talk about the bad stuff. That's great, do it, let it all out. But make sure you're done in less than 10-20 minutes, depending on the length of the entire meeting.

You see, venting is not the real point of the meeting, or at least not the only one. We're conducting retrospectives to improve as a team, which is hardly done by an hour or two of complaining all around. At one point, you need to shift away the focus from feelings onto the underlying problems and their potential solutions.

Second thing on the list... focusing on everything else and everybody else.

Ah, this other team does (not) this and that!

Ah, this stupid legacy code that we inherited!

Ah, this tool that we're missing or doesn't work as we expect it to work!

Ah, these company processes slowing us down!

Ah, these changing requirements!

Do you see a pattern here? Ah, wait, I already spoiled the answer.

Bad news, placing the responsibility on other people and external factors is not going to move your project forward and improve the way your team works.

Good news, at least you identified some pain points. In most cases, you can directly translate these into something your team can tackle:

WE are not collaborating with the other team effectively enough.

WE are not refactoring hard enough on a day-to-day basis.

WE didn't ensure we have the right tools for the job.

WE haven't figured how to work effectively along with company's processes and/or WE are not pushing hard enough to change ineffective ones.

WE don't have a short-enough feedback loop.

Look, this is not to say that you and your team are responsible for every bad thing that happens in your project/company. I'm just saying that during a retrospective you should look for ways to either:

fix bad things you can influence
work effectively despite the things you can't influence (either temporarily or permanently)

Understand? Great.

Now that you're in the right, improvement-oriented mindset, my next point should seem pretty obvious.

You. Should. Avoid. Bikeshedding. Really.

It's so easy to dispute over the small, unimportant details - tabs or spaces, this library or that library, this naming convention or that naming convention. Oh, I love it! Let's polish this baby as much as possible!

The dragon lying there somewhere on a lone sticky note or, perhaps, already forgotten, just mentioned in a single sentence? That's difficult. That would require... thinking!

Put simply, your job during the retrospective is to recognize the dragon and come up with a plan to slay it. Petty peasant disputes and issues can be tackled afterwards or not at all if there's not enough time.

Next up...

Wait! Where are you going?! Stop! I'm not done yet!

Em... Okay! Nice talking to you, see you another time!

What Would You Say for... File Tagging?

Grzegorz Ziemonski — Wed, 02 Jan 2019 17:19:01 +0000

For the past few years I spent quite a lot of time pondering the topic of code organization. Where does this file go? Do we split the files by architectural layers or by business areas? That sort of thing.

A few days ago, when doing something completely unrelated, an idea popped into my mind and I'd like to share it with you.

What if, instead of (or alongside) putting files into a single, fixed layout of directories, we simply tagged them (just as we do with posts on DEV) and then based on these tags we could create all the layouts and hierarchies that we find useful?

The tags and layouts could be specified in some sort of file in our repo, say in JSON or YAML:

{
    "tags": {
        "controller": ["src/controller/user-controller.js", ...]
        ...
   },
   "layouts": {
        "layers": ["controller", "model", "view"],
        "domain": ["orders", "catalog"],
        ...
    }
}

Then, based on the tags and layouts that we specified, our text editor/IDE could allow us to conveniently browse the files:

What do you guys think? Would it help you organize your code? Or maybe it solves a problem that's only in my head and nobody else cares?

Also, let me know if something like this already exists. I tried searching online, but apparently I used the wrong search terms.

3 Tips for a Better New Year

Grzegorz Ziemonski — Wed, 02 Jan 2019 11:37:26 +0000

Hello there!

New year's here and we're all ready to change our lives for at least {you.age}-th^1 time, so who wouldn't like a bunch of productivity tips?

I mean, they probably won't change much anyway, but doesn't it feel good to read something like this when you're still pumped and ~~naive~~ motivated?

Enough introduction, we should all probably be working right now instead of reading this (or writing in my case).

1. Acknowledge the Enemy

Whatever you set out to do this year, regardless of whether it's loosing kilograms, learning a language, writing a book, or really anything else, you're going to have to fight this little voice in your head that's trying to ruin everything:

Hey! Don't start today! Monday seems like a better day to start new things... Or better yet, first day of next month! Oh, I mean first working day of next month, of course.

Yeah, that's a good start, so how about we do a little break today and make up for it tomorrow?

No? No breaks? Hey, let's face it. Nobody's going to want to read this book/use this project/{you.desired_outcome}.

Oh, come on. It's going so well, how about you leave the hard part for a while and research some marketing stuff now? I mean, you are going to have to take care of it some time...

Oh noes! This little obstacle breaks everything! You're doomed! You're never going to work around this. It's over. Good game, thanks, bye.

You get the point. Whether it "is" laziness, reason, self-doubt, fear, or whatever else, resistance is there to fight you and stop you from what you want to achieve.

Be ready to fight^2 , to keep going regardless of what this voice is telling you. At the same time, be ready to fail one day and get back to work the next (or next week, or next month).

2. Assure Sustainability

This may come out a little ironic, but just after telling you to fight this little voice that tries to convince you to do less, I'm going to encourage (some of) you to actually do less.

As we consistently keep "playing" below our own expectations and guilt piles up, it's very easy to come up with a great change plan that's, unfortunately, completely unsustainable.

So, before you (start to) burn yourself out with all the plans and resolutions, ask yourself a simple question:

Is this the amount of effort^3 that I'd be willing to put in for the next 5, 10, 20 years?

I mean, what we are (or should be) after is a lifelong positive change, not a temporary burst of greatness followed by a "same as before" rest of the year (or life!).

If you're still unconvinced, let's do some bad, unreliable math:

A great plan of improving 2% every day that we stick to for 20 days and burn out gives us... 1.02 ^ 20 = 1.4859... ... a roughly 50% improvement, which followed by a prolonged period of stagnation actually amounts to far less than that.
A half-great plan of improving 1% every day that we stick to for an entire year gives us... 1.01 ^ 365 = 37.7834... ... a stunning over 3700% improvement, which we continue to build on, because it's so easy.^4

Think about it. Maybe it's better to come up with an easy plan that continues to yield positive effects rather than any other plan that we struggle to stick to.

3. Experiment, experiment, experiment...

If you're as close-minded as I sometimes tend to be, you might find yourself searching for the perfect idea/vision/understanding of code, life, yourself, and many more. You might seek to grasp this perfect picture, this ideal that you should be heading towards before you make any "hasty" decisions.

If the sentence above at least partially describes you, then I've got some bad news. There's a likelihood that you're going to die before you reach your final destination or, in a slightly better case, you'll think that you found the ideal just to realize you were wrong.

But hey, there's an alternative approach that the tip header above already spoiled: experiment!

If you have an, however imperfect, improvement idea, "just"^5 go for it and see where it takes you.

If you have a bunch of ideas, but don't know which one to follow, try a few of them and pick one that you like best.

If you don't have time to try a few, follow your gut and pick one.

Stay open-minded. We rarely have all the information we might need to make a fully-informed decision and so be it. If anything, it makes our lives more interesting!

And for {you.deity}'s sake, don't sweat it. Unless you're working on a space mission, it's probably not going to matter much if it fails.^6 Aaand you're probably going to fail much less than you might expect.

Final Words

I have no idea why a post that was initially meant to be a bunch of coding productivity tips turned into this new-year-self-help thing, but here it is. I hope you didn't hate it and it'll be great if at least one person finds it valuable. The coding tips will have to wait for another strike of inspiration.

Have a great new year!

^1 Yes, you're this old now!
^2 Also, read some of Steven Pressfield's books, they're very good and they paint a pretty good picture of what resistance is and how we can fight it.
^3 It's funny that just when I was writing this words, I got a big strike from resistance saying that this is a DEV community, not a bunch of self-help maniacs, and you will all either ignore or hate this post.
^4 Who doesn't love bad, unreliable math?!
^5 I put "just" in quotes, because things are always easier said than done. So a "just do it" for me, might be an "overcome a big dragon for you" and I'm trying to respect that.
^6 Well, as long as nobody dies, failure of a space mission isn't that bad either.

My First Visual Studio Code Extension

Grzegorz Ziemonski — Tue, 27 Nov 2018 17:50:46 +0000

Some two days ago, I was thinking about how to optimize my way of navigating code through keybindings and I got this idea: what if I could just "point" the editor to the right place, without necessarily figuring out how to get there?

My first idea was to divide the visible editor's area into a grid in which every cell would have an assigned keybinding. In case there's more precision needed, there could be a second, smaller grid, made just of the cell that you selected before.

As I played with this idea in my mind, I decided that it's not really that great and not that easy to implement in a usable way. But then something else came to my mind...

Some months ago, when I was all about keyboard navigation and keybindings, I used a browser extension that allowed me to click on stuff based on 1-3 letter codes, popping up whenever I want to go somewhere.

This way of navigating resonated much more with my inner dev and seemed much easier to implement for a complete noob such as me.

Of course, I started off by trying to find something like this implemented by someone else already, but I didn't really know what exactly should I search for, so after a few tries I've given up.

And so, yesterday and today, I've coded furiously, spending way too much time on this, but I have the basic idea working:

You simply press Alt+A and a list of "combinations" pops up in different places of your code. Once you type a character combination, you will be taken to the desired place in the code. While in "navigation mode", you can also scroll up and down using f and j keys respectively.

I have to admit that the code is far from perfect and it probably doesn't always work right. Still, at the same time, I'm super curious what other people (i.e. you!) think about it and I'm realistic enough to know that it will probably never be perfect.

So here it is, my first Visual Studio Code extension:
https://github.com/goyozi/visual-nav

Let me know what you guys think!