Make Webpack source code more beginner-friendly #824

Open
gaearon opened this Issue Feb 25, 2015 · 7 comments

Projects

None yet

7 participants

@gaearon
Contributor
gaearon commented Feb 25, 2015

I understand this is a very controversial topic and I don't want anyone, especially @sokra, to feel offended. Please feel free to close if you consider my request inappropriate.

I was having a Twitter conversation with @markdalgleish about Webpack, and we both share the view that Webpack's source can be hard to read. (example)

The design is outstanding, and this allows each module to be written as a plugin responding to several compiler events, but on the other hand most of the code is written as nested anonymous functions instead of compiler event handlers, with little outside functions. To outsiders looking to tweak or understand Webpack, myself included, this proves to be a problem, and it's, in my opinion, an unnecessary barrier to adoption and outside contributions.

Personally, I'd find it easier to comprehend if there was little to no nesting in the compiler plugins, and anonymous functions were named and extracted. This would also solve the problem of deep conditions and loops. A potential small upside is improving performance / memory usage by avoiding too much closures. We made a similar refactoring in @babel, so maybe @sebmck can shed some light on whether this helped make codebase easier to maintain and understand.

As a style nit, I'd also consider converting from tabs to spaces (not kidding) to improve Github display. Yes, I do believe it's important and pragmatic issue: Github chooses 8 spaces for displaying tabs, whereas the most widespread JavaScript standard, used by React and a ton other libs, is 2 spaces. This aids in preventing alienation for developers taking a peek at how everything works. IMO it's part of the experience and unless we can persuade Github to make “tab size” a project preference, it's worth doing.

I wonder how much of this is intentional, whether you agree with me—or any feedback really.
Thanks for considering this!

@kittens
kittens commented Feb 25, 2015

A potential small upside is improving performance / memory usage by avoiding too much closures. We made a similar refactoring in @babel, so maybe @sebmck can shed some light on whether this helped make codebase easier to maintain and understand.

Not sure if the same paradigm could be applied to webpack very easily. I'm entirely ignorant about the internals so this will be the only thing I say on the matter. It did make it easier to maintain since traversal logic was abstracted out of the transformation logic in a really nice and clean way (thanks for that @gaearon!) part of what made this easy was that a lot of logic was already abstracted away so abstracting out more was pretty seamless.

@gaearon
Contributor
gaearon commented Feb 25, 2015

part of what made this easy was that a lot of logic was already abstracted away so abstracting out more was pretty seamless.

This is how I feel about Webpack. Module boundaries are separated in a very good way in Webpack source, and I wish inter-module functional boundaries were the same.

@briandipalma

You just need to append ?ts=4 to a URL and GitHub will display tabs sensibly. Tabs have semantic value in indentation terms but spaces have none. The more useful change would be to refactor the code.

@deepsweet
Contributor

+1.

also tools like ESLint and JSCS can be very useful here.

@gaearon
Contributor
gaearon commented Feb 26, 2015

You just need to append ?ts=4 to a URL and GitHub will display tabs sensibly. Tabs have semantic value in indentation terms but spaces have none.

I see where you're coming from and I totally get this perspective. However somebody choosing between Browserify + plugins versus Webpack will likely not append anything to the URL. They'd look in the source, and make up their first impression about whether it is easy or difficult to extend, debug or tweak it. Anything we can do to make that first impression feel more familiar and easy, is worth doing IMO. There are of course downsides, such as screwing up git blame and existing pull requests. So I'm not saying it's an easy decision to take, or that there is a single right way. Perhaps you're right and it's not worth it.

@sokra
Member
sokra commented Feb 27, 2015

I don't want to start a tabs vs. spaces discussion. Complain to Github that they display tabs so badly, no other code editor uses 8 space tabs.

@gaearon I aggree that some files could be easier to read with better code style, (The posted example doesn't look so bad... It only has 140 LOC ;) ) but I hardly find the time to answer all the issues and chat messages... (I already started to wait some time, most issues solve themselve after a while hihi)... If you want to add some comments feel free to send a PR :p

@jhnns
Member
jhnns commented Mar 2, 2015

I have to agree with @gaearon: I also have difficulties to understand the source code. 😁

@bebraw bebraw added the enhancement label Nov 15, 2015
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment