Hacker News Reader

Comment by xrd | Hacker News Reader

When I was interviewing GitHub employees for my book (https://buildingtoolswithgithub.teddyhyde.io/) one of them made a surprising comment. Early on, his GitHub teammates told him he should create an empty PR with a plan of attack before writing any code. I thought it was a brilliant idea and most teams don't do this. Smart of them to make this a separate feature instead of just bolting on WIP.

View on HN

My team recently started requiring an implementation proposal on the issue that has to be approved by their peers. It saves a lot of wasted effort by exploring the problem domain collaboratively before development begins.

I’ve seen people suggest this and then the horror on other engineers faces that follows. In my opinion, the difference between a good eng/dev and a great one is that they recognize when the effort is too big to chew in one bite, too unknown to reason about clearly without a plan, and/or too many gotchas already exist in the codebase to make it easy.

The great developers I’ve known would pull back and think about the problem longer, draft up some plans and noodle on it with colleagues and I love that foresight.

The problem with a policy like this is that you’re slowing everything down for the sake of the few that might need it. Your team leads should be able to determine which ones should require the investigation and keep the team moving efficiently.

It shouldn't be slowing good developers down, it should just be changing the order they were already doing things. One of the most fundamental ideas I took away from my Software Engineering course in college was that catching errors early in the development process is more efficient than catching them later. It is a lot faster to grind out ideas in the planning phase than to churn during code review, because the development and code review processes are a lot slower than just replying to comments.

More importantly, when experienced developers formalize their reasoning for a proposal, less experienced developers can learn from it. That same knowledge becomes archived in a format that is easy to discover and consume in the future.

Someone suggested this on my team. I personally don’t like the idea because these policies often times lead to bureaucracy and then nothing getting released. It is not that I am against thinking ahead but if i have to in details explain everything I do, then more time is spent documenting than actually creating which is the part I enjoy.

I get it, that's indeed the fun part.

But, do you believe the statistic that 90% of the cost of software is the maintenance?

If so, then the only way you can be a mythical 10x engineer is if you are willing to do things that really reduce the team costs. Everything else about 10x engineers is just mythology.

I think this is an example / practice of one of those things you can do for your team. Communicating clearly up front, being willing to discuss and alter poor thinking (everyone does it) is what turns individual contributors into powerful team members. If you just start with coding, you are missing all that part of it.

Documenting/communicating what you do is important but when it becomes a process it can really be detrimental. Every new feature won’t take the same amount of time and having to spent time writing down my approach for a task that will only take a few days will likely just limit me. That time could be spent on writing (more) tests which is also a form of documentation. If we say that 9/10 times a solution is good, the time saved not writing down the approach could accumulate to 1 rewrite. Basically for me it boils down to some of the agile values and principless:

- Individuals and interactions over processes and tools

- Working software over comprehensive documentation

- Working software is the primary measure of progress.

- The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.

https://agilemanifesto.org/principles.html

> do you believe the statistic that 90% of the cost of software is the maintenance?

Hmmm. Apart from the very suspicious number (90%) I wonder what exactly it's meant by "maintenance". Because it could be bug fixing, adding or changing features, refactoring, server or db administration, etc. And what period of time is included in the "maintenance" phase: one year, ten, a century?

It really depends on the team. There are many cases in my memory where it made sense to code out the skeleton of the plan, especially at integration points and module interfaces, so that it's explicitly clear to other developers what you plan to do.

White-boarding doesn't really address the problem because some of the thorny issues really are substantive scalability or maintainability considerations. I've found it much easier to discuss with mocked code.

Agree, it depends on company and team :)

We tend to split workloads among teams based on timezones, so using placeholder PRs are required if you're handing your ticket over to another timezone for the night.

If your workplace is optimizing for your enjoyment, there is probably a serious problem afoot. The value of thinking ahead, to be clear, is that it enables you to "actually create" something that isn't ill thought out, or worse, of no actual use to any person. It also allows your work to be understood by other people, who might have to duplicate it, review it, or extend it in the future. It is indeed unfortunate that all of these legitimate demands should intrude on your time that could instead be spent spewing out code.

Have to disagree. Many places try to optimize for enjoyment so they can keep their employees.

There is a time and place for everything. If you a working on a project that takes months it should be planned ahead but if it only takes a few days you might not need. Let us not forget why we got rid of waterfall model.

> Let us not forget why we got rid of waterfall model.

It's actually doubtful it ever existed: its first formal description, in the 1970s, is used as an example of a model that doesn't work.

Let me formulate the Godwin-Udik's law:

"As an online discussion on development practices grows longer, the probability of a mention of waterfall as a negative example approaches 1"

It was actually mandated for many government projects for a while. A good history of iterative development can be read here: http://www.craiglarman.com/wiki/downloads/misc/history-of-it...

> It was actually mandated for many government projects for a while

I have no clue about this, but I suspect that the government, rather than mandating a software development methodology, simply used to agree beforehand on what was to be delivered and expected to have it delivered at the end of the process. It's a constraint on how you sign contracts with external suppliers, not on how you write code- though I understand that the first influences the second.

In many industries as well as many government branches it still works just like that. They do not mandate a way of "writing the code", but software projects must pass gates and receive approvals at each stage before getting funding. They have to provide comprehensive analysis and architecture documentation that cover everything under the sun before a single line of code is written. And then, once a dev team starts coding, it has to go through the whole loop and if something specified doesn't make sense "on the real world". Or, more often, they just do the proper thing without telling anyone.

Interesting! Too young to have experienced waterfall model in a workplace. Are you saying it did not exists. If so what was the agile manifest a response to?

> what was the agile manifest a response to?

Frankly I don't know. The Manifesto itself is not very clear about it. I've worked in agile and non-agile companies, but none used a waterfall model. If anything, agile adoption always meant more process (stories, standups, planning, retrospectives, etc.) rather than less. Before or without agile, the structuring of work has been mostly the same, albeit without the formal process defined by this or that agile methodology (to be fair, scrum is the only one I've ever seen).

Writing down what you intend to do and verifying with your team it is sensible is not "the waterfall model". This "I just want to code" attitude is a major disease of young programmers and a leading cause of shitty software. Think ahead. Write it down. You are not a lonesome dove.

Thats a fair point, but I did not say that there should be no communication about the work you do. We all work differently and I think it is sensible to let each employee have some form of independence of how they want to structure their own work. If the feature is a few days of work let me work on it like I prefer and then I can submit with a nice description and thought process.

Let us also not forget about all the time wasted on getting your plan validated. Or how your validated plan is completely screwed only realized after you start implementing it. Pros and cons to each solution.

Again, there is no justification for just jumping in and writing code. Would you cut wood without measuring it first? Would you start soldering without laying out a circuit? Would you write an essay without an outline? You could do all of these things, but the results are guaranteed to be crap.

Why not add the plan of attack to the issue in the issue tracker?

In my experience, communicating too much in the issue tracker tends to invite unnecessary discussion/bikeshedding with people who don't need to know the plan of attack. Our support staff are on our issue tracker, but not on our PRs.

Stuff in the PRs is developers-only.

It makes sense to separate what we want to achieve and how we gonna do it. You may actually have several WIP MRs for one ticket.

I think this feature is meant to be a good middle ground rather than having one issue and one PR ticket. DO you want an issue with added patch set power, or a PR with better collaboration? They'd look pretty similar either way. They went with the latter.

Back when I was first doing XP style development, we did everything with trunk based development (TBD). As a rule, we pushed to trunk (master) every 20 minutes or so. Since we were all co-located (i.e. in the same time zone and working relatively similar hours) it meant that there would be a push to trunk every 5 minutes or so (frequency depended on the team size, of course). We read all of the diffs between trunk and our branch before we merged our code -- and integrated with any changes.

Probably most people won't realise, but it was in that kind of situation that "continuous integration servers" came into being. The idea was that after you pushed to trunk, the tests would run (and in those days we slapped your fingers if the test suite ran for more than a minute or two -- for reasons which will become obvious) and you would have a minute or two to fix any gaffs you made merging conflicts, etc. If you wanted to merge your code, you would wait until the CI server gave a green light, so if the tests were slow, it would be a major PITA.

The massive upside of this process was that you always knew what your colleagues were planning to do. You saw all their progress every 20 minutes! You integrated with their changes! If you saw a problem, you yelled over the cubicle wall and said, "Hey that won't work because I'm doing X" -- saving both you and your colleague hours of wasted effort.

TBD in this style is hard, but very rewarding. The main reason I don't practice it these days is because 1) We have continuous deployment and you don't want to deploy unfinished work 2) The teams I work on these days are distributed (and I'm 9 timezone hours away from their day). However, I really miss that immediate feedback and the seemingly effortless way in which everyone on the team is kept completely in sync. I've never found anything that even comes close (and I've done the "preliminary PR" thing many times).

That was with a very small team? Seems that if you get to only five people or so you'd already be spending most of your time understanding their commits.

In my experience, not so much? You'll need to worry if you're working on tasks that touch the same corner of the codebase, but larger teams tend to correlate with larger codebases, meaning that's not necessarily more likely.

That sort of XP style development also tends to come hand-in-hand with near-constant pair programming. So even if the conceptual limit is "5 sets of committers", that's still double the actual team size. And in practice, the cross-pollination that comes with swapping pairs every day or every few days means there's less of a cognitive load to needing to be aware of what's going on, since chances are either you or your pair already has context.

Indeed, code review shouldn't be architecture review. At that point it's too late and the friction/cost of revisiting the structure is often high. Early sign-off on broad strategy is great for productivity even if it takes a while to document the approach ahead of time.

We do this as a design document on a wiki. It's more long lasting that way and richer with better text and media support.

One of my previous teams used to do something similar, but the initial PR would be for a change to the docs for the project. Would be great, because the docs would be updated to reflect any new changes automatically.

Is there actually a way to do this, if there is no code difference between your new branch and the base?

IIRC, you just need a commit different in order to open a PR with github. To make an empty commit:

    git commit --allow-empty -m 'Empty commit so I can open a PR'

Is that even necessary? I would have thought that simply making the branch and pushing it while it's on the same commit as the branch you're branching from would be enough.

You can't merge a branch that is even with another.

Well, sites like GitHub could be designed so the PR appears as merged from the beginning and then enabling the "merge" button, once more commits are available. Doing it this way also allows to naturally support merging a PR/MR more than once, which I don't know if it's undesirable, but it more closely aligns with what git supports.

I thought Github looked for an actual code difference in the PR creation process, but it seems you're correct! Thanks for the tip.

Well I personally like to start by writing the documentation first. That way your documentation changes become essentially your 'plan of attack' rather than having to write it out explicitly.

The way I've done this before is to have a directory in the project called TODO. In the directory, I add a file with the same name as the feature branch I'm going to work on. I put a description of the work I'm going to do (and any TODOs if I think of them). I commit that and submit a PR with the title "DO NOT MERGE -- whatever".

I find that nobody looks at them, though. :-)

In my team we'll just create a README or TODO and make a PR with that.

Reply on news.ycombinator.com