Why I close pull requests • Hacker News Board

Re: Why I close pull requests

#91

Post by optionalparens » Thu, Dec 29, 2016, 5:39 AM UTC

fdsfsaa wrote: post #47

yegle wrote: post #13

At Google, if you want to implement new features (or large refactoring), you'll need to write a design doc. In which, you should answer questions your reviewers might ask (common questions like: why do you want to do this, what are the alternatives, how components interactive with each other before/after your change). This is something like Python's PEP: you need a proposal to convince your reviewer that you have put…

Requiring permission to do work is the enemy of progress and engineering dignity. It creates a presumption of incompetence and an atmosphere of low trust that punishes people who want to push the envelope of what's possible. Google's design document culture is bad. Google has succeeded in spite of it. In my experience, having worked at many large tech companies, design documents obfuscate, not enlighten. They become…

This attitude strikes me as very SV/HN and while I can appreciate certain elements here, the answer is the typical one - "It depends."

Rather than regurgitate what most people here already said, let me list a few programming projects, domains, and tasks where at least thinking about design if not writing design documents or spending days, weeks, or months figuring it all out is worthwhile.

* Programming Languages

* Databases

* Operating Systems

* Medical Devices

* Safety Equipment

* Streaming containers/formats

* Encryption

* Security

* Manufacturing/Robotics

* Aerospace / Space

* App Dev Frameworks

* Game Engines

I could go on.

The point here is that there are plenty of things where thinking about it up front is beneficial, if not required, especially if some combination (but not limited to) the following are true:

* Lives are at stake

* Changing it later would be hard (programming languages are an egregious offender, I won't name names)

* Customer adoption will completely derail or forbid architectural changes

* Fixing it will require essentially doing it again from scratch

* Changes will force the creation of patches that will incrementally kill the project or slow future development

Frankly, I think we have too many things that are poorly designed. Most projects I see in nearly any domain are mostly set in stone once time and money is added to the mix. Everyone talks about redoing or fixing things, but it rarely happens except for minor changes. As projects scale up, few people can afford to constantly back out lots of changes and rearchitect everything. Those that do usually fail or don't get a good ROI, and those that don't change fail anyway.

I've worked with all kinds of people and though there are people I have great admiration for, I can safely say that 99% of them are idiots and have no business being programmers. I know it sounds harsh, but I've been doing this a long time and have worked with all kinds of people. Too often I see the programmer's equivalent of an illiterate child that gets pushed through high school. So no, I don't trust people to do the right thing, I merely trust most people I work with to not act maliciously. Most of all, I don't trust myself. As the progression goes as a programmer - your code sucks -> my code sucks -> all code sucks -> my code sucks but I'll live with it, hope it is better than most, and ask people smarter than me for help.

Most better developers I know do in fact right some form of design documents, even if it's just notes and justification why X or Y won't work, but Z "might" work. Many also take a lot of time to think about something before writing any code, but once they do, they actually finish much quicker with less bugs than the young programmers who want to "move fast." Of course none of this is universal, and as I said, it all just "depends." What do I know?

Re: Why I close pull requests

#92

Post by dismantlethesun » Thu, Dec 29, 2016, 5:43 AM UTC

Nadya wrote: post #25

asdkjfsad888 wrote: post #24

Earlier quoted context omitted.

How do you know they obviously need the change by making a decision away from the project management discussions? Perhaps a solution has been discussed and is incoming from a regular developer? They could deprecate the module where the change is "obviously" needed in a larger fix. Frame it a different way: You're basing the needs of a project on your view of it, which, minus discussing things with project mgmt before…

You completely misunderstood who was needing the fix. In this case, it was the person who spent time fixing it. They likely fixed it because they need the fix . Doesn't matter if the entire module becomes deprecated. They'll stay back with their fix (likely). Doesn't matter if another solution is inbound, they needed the fix now and not when a patch lands. And since they already took the time to fix it - little time…

Actually, sometimes people push changes because they intellectually think it's a better architecture or public API, but they can't survive as a fork.

They need the frequent bug fixes and upgrades from the mainline, so they really do waste their time if their changest is not approved.

Re: Why I close pull requests

#93

Post by Spooky23 » Thu, Dec 29, 2016, 5:47 AM UTC

fdsfsaa wrote: post #55

stinkytaco wrote: post #50

Earlier quoted context omitted.

I can't comment on Google's culture, but: >Design documents turn every feature into a half-assed, lowest-common-denominator risk-minimized shell of itself. Sounds like a sentence written by someone who is an engineer and not a support staff or a user, i.e the people who have to deal with the fallout of every feature change and every engineering decision. I could just as easily substitute "feature driven design" into…

> Sounds like a sentence written by someone who is an engineer and not a support staff or a user Do support staff and users sign off on design documents? "No" is the universal answer. Are you claiming that engineers aren't reasonable human beings who can take support staff and user concerns into account on their own? What makes you think the people reviewing design documents can do that? Is it that you just trust a s…

You don't know everything, and if you do, your replacement 3 years from now won't.

Engineering is a process to solve problems at its core. Fundamentally, you cannot solve problems without know on what the the questions are.

Re: Why I close pull requests

#94

Post by fdsfsaa » Thu, Dec 29, 2016, 6:00 AM UTC

jimmywanger wrote: post #74

fdsfsaa wrote: post #59

Earlier quoted context omitted.

> We write design docs at Google to communicate ideas with each other. I have no problem with individual developers choosing to circulate documents in order to solicit feedback. My objection is to rigid processes that force engineers to write documents. Mandatory design documents for "communication" invariably morph into checklists of required signoffs from people who have little incentive to say "yes". In this way,…

> Prove it. Provide evidence. In my experience... That's amusing, that you want solid evidence, yet you're willing to use your own anecdotes. > Mandatory design documents for "communication" invariably morph into checklists of required signoffs from people who have little incentive to say "yes". Or they make you think about things that are not obvious on first glance, especially at Google scale. For any customer faci…

> That's amusing, that you want solid evidence, yet you're willing to use your own anecdotes.

I'm not the one presenting my anecdotes as fact: "The fact is that, on average, design doc+code takes less time than code without design".

Anyway, you've very clearly articulated the conventional wisdom of big companies originating in a certain era of computing. Conventional wisdom isn't necessarily wrong, but it's not necessarily right for all time either. There are companies with data needs, user counts, and codebase sizes on par with Google that don't practice Google-style process, yet succeed anyway. That these companies have succeeded without Google's process is evidence that Google's process is unnecessary, at least in today's environment.

> SQL injection and XSS vulnerabilities for example

Code-level concerns. You're not going to stop SQL injection by looking at some high-level design document. The same goes for r2l text layout bugs.

> it's worth taking six months adding a checkbox to take every possible step possible to ensure that doesn't leak a security vulnerability somewhere.

Keep that in mind when smaller competitors surpass you. It's easy to say that Google's codebase represents 18 years of work. I strongly suspect that it wouldn't take so long to do starting today.

Look at self-driving cars: how long has Google been working on them? How long has Uber? Whose cars are serving real-world passengers today?

These days, we have 1) very good continuous integration systems, 2) good code review tools, 3) fast shipping vehicles, and 4) continually improving static analysis. These things were unavailable (at least at adequate quality levels) when Google started its design culture.

Maybe the conventional wisdom you articulate might have been an optimum some time ago. These days, I think it's far too process-heavy and that Google and similar companies haven't kept up with the times.

> Just because your individual progress is slow, doesn't mean that the progress of the team is slow

It means that the team is inefficient. Communication overhead goes as N^2, after all. Google's teams are notoriously huge. When you see that a startup (or even another > $1 billion company) can do the same damn thing Google does and put a quarter of the people on the task, maybe it's time to wonder whether Google is doing something wrong.

If developers feel like process is slowing them down, maybe you should listen to them.

> One breaking change in say Google adwords can undo literally man years of work.

It's easy to look at a few failures and conclude that you need to add process to fix whatever went wrong. It takes much more foresight and wisdom to see that this process probably costs more man years in overhead and inflexibility than you spend fixing the occasional mistake.

Re: Why I close pull requests

#95

Post by fdsfsaa » Thu, Dec 29, 2016, 6:09 AM UTC

zardeh wrote: post #70

fdsfsaa wrote: post #55

Earlier quoted context omitted.

> Sounds like a sentence written by someone who is an engineer and not a support staff or a user Do support staff and users sign off on design documents? "No" is the universal answer. Are you claiming that engineers aren't reasonable human beings who can take support staff and user concerns into account on their own? What makes you think the people reviewing design documents can do that? Is it that you just trust a s…

>You shouldn't hire people who don't give enough of a shit to take the big picture into account. At a certain point you can't. I was recently asked to implement a feature for a usecase for another engineer. It required a design doc and review by a few representatives from related teams. He and I wrote the doc, and the initial review was that any solution that would fix his usecase would break the testing infrastructu…

> break the testing infrastructure for practically every other developer in the building

Why wouldn't continuous integration have caught that bug? If a diff breaks the build, it shouldn't land. If a diff causes tests to fail, it shouldn't land. If a diff lands anyway and causes problems, any developer negatively affected should be able to insta-revert the diff.

How does a design document help?

Re: Why I close pull requests

#96

Post by fdsfsaa » Thu, Dec 29, 2016, 6:12 AM UTC

tlogan wrote: post #76

fdsfsaa wrote: post #47

Earlier quoted context omitted.

Requiring permission to do work is the enemy of progress and engineering dignity. It creates a presumption of incompetence and an atmosphere of low trust that punishes people who want to push the envelope of what's possible. Google's design document culture is bad. Google has succeeded in spite of it. In my experience, having worked at many large tech companies, design documents obfuscate, not enlighten. They become…

Design, functionality, and test specifications are very important. But the process must be monitored and be very flexible. I'm not familiar with Google system, but in other big corporations the problem is that you end up with system which does not allow exceptions - so engineers end up requiring writing 10 different documents to make a small change which can be explain on one page and everybody will get it: support,…

I think the pathologies you mention are inevitable once it becomes acceptable to address technical problems by adding process like mandatory design document signoff. The only way to avoid these pathologies is to take a hard stand against process.

Re: Why I close pull requests

#97

Post by fdsfsaa » Thu, Dec 29, 2016, 6:14 AM UTC

optionalparens wrote: post #91

fdsfsaa wrote: post #47

Earlier quoted context omitted.

Requiring permission to do work is the enemy of progress and engineering dignity. It creates a presumption of incompetence and an atmosphere of low trust that punishes people who want to push the envelope of what's possible. Google's design document culture is bad. Google has succeeded in spite of it. In my experience, having worked at many large tech companies, design documents obfuscate, not enlighten. They become…

This attitude strikes me as very SV/HN and while I can appreciate certain elements here, the answer is the typical one - "It depends." Rather than regurgitate what most people here already said, let me list a few programming projects, domains, and tasks where at least thinking about design if not writing design documents or spending days, weeks, or months figuring it all out is worthwhile. * Programming Languages * D…

> 99% of them are idiots and have no business being programmers

I feel the same way. If you have a group of idiots, you need process as a harm reduction measure. A very high contributor bar is a prerequisite for a process-light environment, because if you can't trust people to do the right thing, you need a system to force them into a conservative approximation of the right thing, and this system is called process.

Re: Why I close pull requests

#98

Post by fdsfsaa » Thu, Dec 29, 2016, 6:22 AM UTC

dismantlethesun wrote: post #90

fdsfsaa wrote: post #55

Earlier quoted context omitted.

> Sounds like a sentence written by someone who is an engineer and not a support staff or a user Do support staff and users sign off on design documents? "No" is the universal answer. Are you claiming that engineers aren't reasonable human beings who can take support staff and user concerns into account on their own? What makes you think the people reviewing design documents can do that? Is it that you just trust a s…

> You shouldn't hire people who don't give enough of a shit to take the big picture into account. Even if you care, you can't know the entire story. I work for a small company, tiny compared to Google, but often we run into someone proposing a change that backtracks on a strategy decided 2 years ago. Luckily it was encoded in a design document or else, how would anyone new find out about it? New people want to know t…

> backtracks on a strategy decided 2 years ago

Why should anyone be bound today by decisions made two years ago? Maybe that strategy no longer makes sense.

I've seen it go both ways. On one hand, sometimes a new developer in an old codebase does something "against the grain" of the system due to unfamiliarity or JavaScript-induced brain damage. On the other hand, sometimes circumstances change and even good old designs become obsolete.

A culture of good taste and transmission of institutional knowledge helps preserve the good aspects of design. I don't think design documents help: they're just bytes on a disk. Unless you have people to enforce them, these documents won't do a thing. If you do have people who know what the system is supposed to look like and who shepherd changes to work with the original design, you don't need the design document.

Re: Why I close pull requests

#99

Post by fdsfsaa » Thu, Dec 29, 2016, 6:26 AM UTC

dismantlethesun wrote: post #88

fdsfsaa wrote: post #47

Earlier quoted context omitted.

Requiring permission to do work is the enemy of progress and engineering dignity. It creates a presumption of incompetence and an atmosphere of low trust that punishes people who want to push the envelope of what's possible. Google's design document culture is bad. Google has succeeded in spite of it. In my experience, having worked at many large tech companies, design documents obfuscate, not enlighten. They become…

> In my experience, having worked at many large tech companies, design documents obfuscate, not enlighten. They become increasingly out-of-date as the code evolves, creating anti-documentation that makes it take longer to understand code. Yes, yes, people should update design documents as the code evolves. Everyone knows that in practice, nobody updates old design documents. My experience has been the reverse, precis…

> A piece of code with a design document at least has a historical record of what the original aims of the project were, and a written rationale for why they took certain approaches.

That information is very useful, particularly as a comment or a commit message. Storing this information in a separate unversioned document off on some enterprise management system makes it harder to find. If you put the rationale for a change in the commit message, the rationale is right there when you run blame!

Re: Why I close pull requests

#100

Post by fdsfsaa » Thu, Dec 29, 2016, 6:28 AM UTC

zardeh wrote: post #71

fdsfsaa wrote: post #59

Earlier quoted context omitted.

> We write design docs at Google to communicate ideas with each other. I have no problem with individual developers choosing to circulate documents in order to solicit feedback. My objection is to rigid processes that force engineers to write documents. Mandatory design documents for "communication" invariably morph into checklists of required signoffs from people who have little incentive to say "yes". In this way,…

To clarify here, what kinds of changes do you think require a design document?

I don't think any specific type of change should require a design document. That framing presupposes too much hierarchy. Design documents, like code reviews and tests, ought to be helpful tools for developers, not requirements imposed from above. I've worked at companies that didn't require design documents, but occasionally wrote them anyway because I wanted feedback.

Another trigger could be a reviewer commenting, "Hey, this diff stack is getting pretty tangled. Can you write something that describes how it all fits together?"

You should trust your developers' judgement.