search

codeforamerica / amiinlv

Am I In Las Vegas? Sometimes it's hard to know, because the city limits have the complexity of a fractal curve.
http://amiinlasvegas.com/
BSD 3-Clause "New" or "Revised" License
10 stars 5 forks source link

Deprecate Extraneous Frameworks #4

Closed lovehandle closed 11 years ago

lovehandle commented 11 years ago

@louh @daguar

Was taking a look at the thread in Campfire last night, and saw the conversation the two of you were having. You both bring up some interesting thoughts, and I wanted to move the discussion to a more public forum so others could chime in.

Let me preface by saying that I have absolutely no qualms with removing the three frameworks from this project (HAML, Less, Coffeescript); I used them simply because they made my life easier (as frameworks are wont to do). I agree with you that it's a lot to learn for someone that is not familiar with those three stacks.

My reasoning in using each of the frameworks mentioned above is that it creates cleaner code, and in a number of ways I value good code more than I value collaboration (which reminds me of a conversation I had with @ahhrrr regarding Git usage). Perhaps it's is out of line with the CfA mission, but I would rather have a well-engineered project with 2 contributors than a poorly-engineered project with 20 contributors.

In this case, I'll admit I let the framework creep get out of hand, but I refuse to believe that the use of frameworks in general should be excluded from open source projects (e.g. is it really unreasonable that I used Backbone.js to clean up the client side code). There has to be a middle ground in which the two concerns (project inclusion vs. good engineering) can meet.

I think there are a number of arguments for making use of popular frameworks in open source projects, but I'd like to open up the discussion before this turns into a novel.

Note: The purpose of this issue is to remove the usage of HAML and Coffeescript from this project (@louh already knows Less, so I'll leave that unless anyone has any objections).

louh commented 11 years ago

Good start to this discussion, thanks Ryan.

My perspective, as someone who joined CfA with a script-kiddie level of code knowledge, is that you're never going to have a well-engineered project with two contributors, if the other contributor is me. You would have to fire me first, and replace me with a competent engineer.

Not that I don't value clean code, because I love clean everything, but I just don't think I speak these languages well enough yet to be elegant.

Right now, it would seem that the stack of frameworks is a roadblock to me being as involved as I would like with our project(s). I'm not unwilling to learn. I actually just assumed I would follow along, and learn quickly. But as it turned out, there was so much I did not know, that I ended up trying to learn everything in one evening, just to redo something I already figured out how to do using vanilla JavaScript. That was really frustrating, especially when I did not know what I was doing wrong.

I should also say that with LESS, I was familiar enough with CSS to ask questions like "Wouldn't it be nice if I could have variables? Wouldn't it be awesome if I could reuse common CSS code like a function?" But I never hung out with the right people and no one told me someone answered those questions already, and once I learned about it, I saw the benefit of it right away. My problem with HAML, CoffeeScript, Backbone etc. isn't that I think you're wrong about its usefulness. It's that I don't understand why I need it yet. So learning all of this right now also doesn't contribute to me feeling like it's a good use of time.

I think we can ramp up to these sorts of things, especially on bigger projects where it's necessary, but I think for the time being you're going to do way more hand holding than you're used to and that might be similarly frustrating for you. And not to speak for every project or person at CfA, but everyone has a different level of interest and it basically means having this discussion around frameworks each time. You could go the easy way and choose to only ever work with people who are at your ability level, or work only with people who will never need to or want to touch your code. Instead, you are stuck with me. And I appreciate that you're being patient and understanding about this.

I actually don't even know where I stand on the debate around using frameworks vs not using them, but I'll close with an allegory, because I actually want to write a novel.

So let's say we're building a house. I'm not the master builder here, but I did work out some of the planning of it, so during construction I decide to be helpful and show up with a hammer.

"That's nice," says the foreman, "but we don't use hammers anymore. We use this device, called a hawsham. It does the same thing as a hammer, but the result looks a lot better. See how these nails go into the wood with a hawsham? Beautiful. Better than any old regular hammer."

"But," I say, "You hold it kind of funny and when I try to use the hawsham these nails don't go in quite the same way you do it. Actually, I think I work even slower. And in the end, all of this wood is getting covered up with drywall, and then someone will move in and never notice the nails. So if it's all the same to you, I think I'd rather stick with the hammer."

So it's a little heavy-handed, but I don't really know how to finish the story. I think you can pick it up from here.

alanjosephwilliams commented 11 years ago

Very curious to see how this conversation shakes out. I'm essentially in Lou's position, but still on the script-kiddie level. Don't have an opinion on the matter, but hoping to glean some nuance for future collaborations.

AJW

On Sun, Mar 24, 2013 at 4:18 PM, Lou Huang notifications@github.com wrote:

Good start to this discussion, thanks Ryan.

My perspective, as someone who joined CfA with a script-kiddie level of code knowledge, is that you're never going to have a well-engineered project with two contributors, if the other contributor is me. You would have to fire me first, and replace me with a competent engineer.

Not that I don't value clean code, because I love clean everything, but I just don't think I speak these languages well enough yet to be elegant.

Right now, it would seem that the stack of frameworks is a roadblock to me being as involved as I would like with our project(s). I'm not unwilling to learn. I actually just assumed I would follow along, and learn quickly. But as it turned out, there was so much I did not know, that I ended up trying to learn everything in one evening, just to redo something I already figured out how to do using vanilla JavaScript. That was really frustrating, especially when I did not know what I was doing wrong.

I should also say that with LESS, I was familiar enough with CSS to ask questions like "Wouldn't it be nice if I could have variables? Wouldn't it be awesome if I could reuse common CSS code like a function?" But I never hung out with the right people and no one told me someone answered those questions already, and once I learned about it, I saw the benefit of it right away. My problem with HAML, CoffeeScript, Backbone etc. isn't that I think you're wrong about its usefulness. It's that I don't understand why I need it yet. So learning all of this right now also doesn't contribute to me feeling like it's a good use of time.

I think we can ramp up to these sorts of things, especially on bigger projects where it's necessary, but I think for the time being you're going to do way more hand holding than you're used to and that might be similarly frustrating for you. And not to speak for every project or person at CfA, but everyone has a different level of interest and it basically means having this discussion around frameworks each time. You could go the easy way and choose to only ever work with people who are at your ability level, or work only with people who will never need to or want to touch your code. Instead, you are stuck with me. And I appreciate that you're being patient and understanding about this.

I actually don't even know where I stand on the debate around using frameworks vs not using them, but I'll close with an allegory, because I like stories.

So let's say we're building a house. I'm not the master builder here, but I did work out some of the planning of it, so during construction I decide to be helpful and show up with a hammer.

"That's nice," says the foreman, "but we don't use hammers anymore. We use this device, called a hawsham. It does the same thing as a hammer, but the result looks a lot better. See how these nails go into the wood with a hawsham? Beautiful. Better than any old regular hammer."

"But," I say, "You hold it kind of funny and when I try to use the hawsham these nails don't go in quite the same way you do it. Actually, I think I work even slower. And in the end, all of this wood is getting covered up with drywall, and then someone will move in and never notice the nails. So if it's all the same to you, I think I'd rather stick with the hammer."

So it's a little heavy-handed, but I don't really know how to finish the story. I think you can pick it up from here.

— Reply to this email directly or view it on GitHubhttps://github.com/codeforamerica/amiinlv/issues/4#issuecomment-15371848 .

e: alan@neighborland.com t: @alanjosephwilli p: 817 713 6264

daguar commented 11 years ago

(So first let me apologize to @rclosner -- even if my Campfire comments weren't terribly inflammatory, looking back at them, my tone was not what I'd like to see in even a semi-public forum. So, sorry Ryan: my bad.)

Thanks to @louh and @rclosner for being so honest and understanding in your writing. It's awesome to see such great respectful articulation of one's logic.

I've got a lot of thoughts on this, and have written and re-written the below more than a few times, so I'm just going to dump a few kernels as concisely as I can manage, and hope it just sparks further conversation:

Goals

There are many other goals to a software project beyond efficiency, delivery time, or strict correctness. At @codeforamerica, there are many explicit other goals: collaboration/openness, process documentation, don't repeat yourself/others, leanness. We have to navigate the trade-offs among these goals.

Code cleanliness

"Clean code" or "good engineering" are not objective: they're about the alignment of implementation with the project goals. NASA code needs to be as efficient and strictly correct as possible, but that's because NASA's goals are fundamentally different: correctness really matters when rockets carrying people will blow up if you segfault.

In the initial project choices here, some metrics of code cleanliness might be (a) how easy it is for you as the lead to work on it and read your own code, (b) how quickly a given person could dive into the code base, and (c) how many people could use the code base (toward the goal of reusability).

By throwing in lots of wrappers which the initial lead dev is familiar with (CoffeeScript, HAML, LESS) it probably makes it easier for him to read his own code, but both diminishes how many people can reuse it/contribute to it, as well as how quickly someone could dive in and grok it.

I think of it as costs and benefits: this is a fairly small project, and I see the benefits of using CS/HAML/LESS as being marginal (slightly easier dev readability). But they drastically increase the barriers to collaboration, when simple HTML/CSS/JS doesn't create much more work.

Backbone is a more difficult call, because it's really more or less vanilla Javascript, so I'd probably agree with @rclosner that it's good to keep in. jQuery is also a difficult call, because it's a great wrapper for a lot of the view actions that could be a separate component/dev role, particularly for a learner whose primary responsibility would not be business logic (see my 'Roles' comment below). But in both cases it really is about...

Process

Team collaboration and process matter. Based on @louh 's comment, I'm guessing one implicit goal of this project was for him to get more comfortable on the front-end dev stuff in advance of larger projects. But I'm also guessing that there wasn't really an explicit sit-down and discussion of what the goals really were. It's hard to navigate trade-offs among goals when there isn't even a clear consensus on them! I'm guessing learning/accessibility was implicitly traded off against other goals (probably dev speed and code correctness). This is no one's fault in particular; it just speaks to the importance of communication.

I find a good approach is to discuss the goals of a project at the outset, commit to using those goals to guide individual decisions, and check in when a decision may veer away from (or even just impact) the initial consensus.

Roles

I think a large part of the tension of what's been expressed to me about this code base is that the division of roles/responsibilities is not clear.

Who's doing what? What are the boundaries between business logic and front-end? Communicating clearly about the architecture, who owns what pieces, and the interfaces of each piece can make everything go a lot more smoothly.

A concrete example I had in mind is that recently @dthompson and I were collaborating on something where he was doing a front-end, single page JS app, and I was building a back-end API. I asked him to tell me what JSON structure he wanted to get, and that was that. All that matters is the interface, and either side can be coded however we want. The upside to this division of responsibility is also that the code is more modular and reusable. You'll notice a not-so-subtle similarity to service-oriented architecture (SOA) that I talk about so much.

I know this is a small project, and all JS, but I could see there being a similar division of components in such a way that each collaborator could own a piece and be clear on the interface between them, even if that's as simple as CSS/HTML and view-functionality-only JS being @louh and business logic JS being @rclosner , which is the traditional dev/designer division IMO.

Anyway, wow, that's still long -- sorry about that. Definitely looking forward to hearing others' thoughts and discussing in person at the office ( :factory: ).

lovehandle commented 11 years ago

Thanks (everyone) for your thoughts! I like where we ended with this, and I'll be curious to see how this discussion evolves throughout the remainder of the fellowship. For now, I'm going to mark this issue as closed. In the case you have more thoughts to add, feel free to re-open this issue.