RubyConf 2015

Usando Git para guardar un registro de las decisiones tomadas al desarrollar un proyecto Ruby

Josh Freeman  · 

Presentación

Vídeo

Transcripción

Extracto de la transcripción automática del vídeo realizada por YouTube.

- All right, let's talk about git. My name's Josh Freeman. I'm a software developer here in San Antonio for Grok Interactive. We're primarily, we turn tacos and caffeine into software and we have pretty good time with it. I want to talk about some stories.

Stories have power. I love a good story. The narrative that the author tries to tell, the context in which these stories are told, the motivations of the characters involved. This talk is not going to be too technical in depth. There's gonna be some how-to, but mostly we're gonna be talking about the communication process that we undergo in software.

And when we get into that, we're gonna start a little bit with compression. Video, music, pictures. There's a certain amount of compression in the data that's fine. We can get away with that, we're good. But when you're trying to tell something, to communicate something, especially textually, compression is not such a good idea.

And we're gonna start this, I'm gonna prove his point with some headlines. From a story that you should know, but has been highly compressed. Headline, "Local farming family murdered "by military police, nephew, 21, solve survivor. " Headline, "Nephew of murdered family leaves home "to join separatist force.

" Headline, "Farmer turned pilot "destroys key military facility. " At this point, who knows what story I'm talking about? Star Wars. So, compression is good in a lot of respects, but if you compress too much, you lose a lot of the benefit of the information and the narrative you're trying to tell.

And that's what I wanna talk about today in avoiding that when we're working with git. So if you like xkcd, certainly you've seen this comic. I'm gonna assume that you understand the basics of git and this is going to be more of an intermediate talk to level up your commit messages.

But as a quick refresher, why do we use git? Well, first of all, using FTP and email to transmit files is dumb. Secondly, versioning of your software is something that we find that we need over and over and over again. And we always want to find out, okay, especially if you worked with designers, right? Designers always have composition dot PSD, composition dot final dot PSD, composition dot final dash two dot PSD, composition dot final oh really this time dot PSD.

Even designers know that there's this need for iterative improvement, that they're never quite done. And software very much is that process, where it's a living thing that grows as your understanding of the business or the domain grows as well. So, is git a communication tool? I posit yes.

When I first started getting the software four or five years ago, I was at a point in my life where I really did not want to talk or work with people. So software was very attractive, right? You just sit at a keyboard all day long behind a screen, minimal interactions with people.

It's great. Well, I quickly found out to be even remotely good at my job, you can't live that way and you can't work that way. And I think, as attending the conference demonstrates, you have to be able to engage with people, whether it's your teammates or your clients, in order to get something productive and useful done.

Git, I think, is the most important tool that we have at our disposal and I think it's also one of the tools that we use sometimes the least effectively. If we use git, it forces us to ask the who, the what, the when, and the where, but it never requires us to ask why.

So, software has three audiences. It has the author, ourselves writing it, it has the team that we're working with, and it has the future maintainers, who may be the same people or completely different people. And communication through both code and your version control needs to be empathetic to all the groups.

Software is the result of thousands of decisions that we make over months, even years. We add this feature, we clarify this method, we change this behavior, and we should be able to answer, have an answer for why these changes were made at each point. So, there's two hard problems in computer science.

Naming things, cache invalidation, and off-by-one errors. And what we're gonna focus on today is the naming things. I firmly fall into the camp of Bob Martin that comments are an apology and if you have to write a comment in order to explain what's going on, typically that means you have not chosen a more effective name for the functions or the methods or the variables that you're using.

I won't say that you should never use a comment, but if you find yourself writing lots of comments, I would suggest to you that you need to find better names to indicate what you're trying to accomplish. The only source of truth is what the code says it is and if there's ever a divergence between your comments and your code, obviously the code is going to be the correct version.

We've all had comments that just drift and get out of date, we've all done it, we've all seen it. So I wanna briefly show something that I did about a year and a half ago. Don't worry about the details, this is some jQuery going on here. But the thing to focus on is the fact that the comment block is two, two and a half times longer than the code it represents.

It doesn't really clarify what's going on and in fact, if you know any jQuery, any of the jQuery API, it's pretty obvious what's going on. Does this method name even describe what's happening? I don't think so. In fact, we need a comment to describe what this thing is supposed to be doing.

In fact, we're not even removing anything. So, I picked a bad name and all this information about what it was doing reflects that. The only stuff in this comment that I would say should be there is probably the parameters and that would be for automatic generation of documentation.

That would make sense, but the rest of this stuff is really information that I was using to learn and explain what was going on, which would be better served thrown in a commit message. So, if you end up writing stuff like this where you have huge chunks of comments to explain small bits of code, your messages probably start to look like this.

[ ... ]

Nota: se han omitido las otras 2.875 palabras de la transcripción completa para cumplir con las normas de «uso razonable» de YouTube.