24 ms·

Developers spend most of their time figuring the system out

839 points by webmaven 5y ago

nuancebydefault 5y ago
This matches my experience. IMO the best alternative tovreading code is to talk about the intent of the system by other coders or architects. Formulating questions is a start of understanding. Getting answers or directions increases understanding even more, for both parties.
Veuxdo 5y ago
Very true. In fact, this was the impetus behind my project. Over the decades there's been a ton of focus on machine learning and big data, but virtual none on human understanding [of systems].
- deleted 5y ago
  [deleted]
- tudorgirba 5y ago
  Do you have a link to your project?
bcbrown 5y ago
Relevant to this article is Peter Naur's paper on Programming as Theory building: https://pages.cs.wisc.edu/~remzi/Naur.pdf https://pages.cs.wisc.edu/~remzi/Naur.pdf He argues that the biggest determinant on whether maintainers on a system they did not build will succeed is whether they will have access to the original developers: "The conclusion seems inescapable that at least with certain kinds of large programs, the continued adaptation, modification, and correction of errors in them, is essentially dependent on a certain kind of knowledge possessed by a certain group of programmers who are closely and continuously connected with them."
- wwweston 5y ago
  See also Bill Thurston's commentary on the nature of mathematical knowledge: "mathematical understanding does not expand in a monotone direction. Our understanding frequently deteriorates as well. There are several obvious mechanisms of decay. The experts in a subject retire and die, or simply move on to other subjects and forget. Mathematics is commonly explained and recorded in symbolic and concrete forms that are easy to communicate, rather than in conceptual forms that are easy to understand once communicated. Translation in the direction conceptual -> concrete and symbolic is much easier than translation in the reverse direction, and symbolic forms often replaces the conceptual forms of understanding. And mathematical conventions and taken-for-granted knowledge change, so older texts may become hard to understand. In short, mathematics only exists in a living community of mathematicians that spreads understanding and breaths life into ideas both old and new." https://mathoverflow.net/questions/43690/whats-a-mathematician-to-do/44213#44213 https://mathoverflow.net/questions/43690/whats-a-mathematici...
  - epolanski 5y ago
    I don't really buy that. Mathematics is by far the biggest and longest running open source project on this planet and we are absolutely able to traverse it by centuries or millenia. This works across languages and cultures. Mathematics is built on a small set of axioms and everything else is defined on top of it and proved. Your comment makes it sound like there is some magic knowledge linked to arcane symbols, when mathematicians are the least interested in symbols and labels, they care about definitions. As with any field if you get in highly specific topics then obviously you are going to lack enough literature and tradition on these topics and something may get lost, but if everyone forgot all they knew about math today we would be easily able to get back to where we are in a just by reading.
    - fantod 5y ago
      > if everyone forgot all they knew about math today we would be easily able to get back to where we are in a just by reading If your definition of "easily" is the amount of work required to become a mathematician, then sure.
- MattGaiser 5y ago
  A former colleague sent me an receipt that had an error from a system we worked on years ago (2 and 3 companies ago respectively). I bet we could tell the current devs where to find the bug pretty easily as we wrote a lot of that code.
- cloogshicer 5y ago
  That paper is amazing. Completely changed my view on programming. For those who find it a bit inaccessible (as I did on my first read), I wrote an article about it a while back, explaining it further and giving real-life examples: https://hiringengineersbook.com/post/autonomy/ https://hiringengineersbook.com/post/autonomy/
  - mehphp 5y ago
    Well that was a great read; thanks for sharing!
  - ilovecaching 5y ago
    Nice article, I enjoyed reading it.
    - cloogshicer 5y ago
      Thanks! :-)
  - mikewarot 5y ago
    >The main value of a software company is the mapping of source code and problem space in the developer’s heads [In linked article] That is a profound conclusion to reach. For the most part, I think it's true. Without someone who wrote/fully understands source code, for example in abandoned software, the source code is a treasure map, the as-built plan of a building. It takes a lot of time and effort to orient yourself with things and make reasonable guesses as to what is going on. This aligns well with the original post.
- magicalhippo 5y ago
  We see something similar with our customers. When our customers have some new projects or change their ERP or whatever, we almost always know better than they do how their systems and procedures work. Like, if they come with a change request we might ask what about X, they'll get all surprised saying no we don't do X, but after a bit of prodding sure enough, they discover they have a worker that's handling X every day. This is simply because we've been around, while they've had multiple new persons cycle through their departments. When they change the ERP system, we've still got the guy who coded the integrations with their previous system.
- amatecha 5y ago
  Text version of that article: https://gist.github.com/onlurking/fc5c81d18cfce9ff81bc968a7f342fb1 https://gist.github.com/onlurking/fc5c81d18cfce9ff81bc968a7f...
mooreds 5y ago
Haha, so true! I've found that for most systems, there are three great ways to "figure it out". * Start from input. (Browser, API, whatever starts a process.) Map from there. * Start from data storage. (Database, flat files, whatever.) How does state get persisted? * How does the system move into production? If you can make a small change (even adding an innocuous comment) and see it all the way from your machine to prod, you can iterate and start to map the system.
- samspenc 5y ago
  A couple of things I found helpful along those lines: * Data storage: what does the schema look like? Even if it is not persisted to a relational DB, is it possible to draw out a schema of a data model and all the relationships ("JOINS") * Add logging to code you are trying to debug but are hard to understand and repro bugs for in production. Once you have logs about the full state that reproduces the error, the issue will be easier to fix. Don't roll out a fix before fully understanding an issue. As a corollary to this: always add a task to remove this verbose logging you added once the bug is fixed!
  - bckr 5y ago
    > Add logging to code you are trying to debug This is a great idea and should absolutely be a standard. There's a whole logging level ("DEBUG") devoted to this that I think goes way underused. Another, related idea is to use a debugger. Using PDB for Python codebases has sped me up A LOT.
    - nine_k 5y ago
      I worked with software where you could change logging level dynamically, per subsystem. The ability to switch to DEBUG level, get a wall of text from a problematic spot, and switch it back to WARN was very, very helpful for troubleshooting prod.
- selectronics 5y ago
  Chiming in that this applies to controls engineering as well (think PLCs). Start from the IO, cross-reference that through the rest to get a feel of chains of causality and how it all works. Oftentimes it's critical to go from zero to applying changes as quickly as possible when unfamiliar (and poorly documented!) machinery is down.
jollybean 5y ago
It's why good abstraction and documentation for it is so powerful - you only need to understand the API and not anything else. We start teaching about software like it's 'algorithms' when that is frankly, almost pedantic. That was never the hard part. Scaling the complexity was always the hard part. Simple, clear code, absent leaky abstractions, enough documentation etc..
- kache_ 5y ago
  The problem with abstractions is that it seems that not making leaky abstractions is difficult for most people (most people making these abstractions don't know about the concept of an abstraction leakage in the first place) Software engineering is extremely difficult
  - jollybean 5y ago
    That they don't even teach 'leaky abstractions' is a bit rich, and as you point out it's hard. And it's not 'hard for most people' it's hard for everyone. Every API is leaky and inconsistent, it's all a matter of degrees. Concise documentation is essential. I'm reading about a Java API for the 5th time and only now just 'getting it' fairy clearly, it's not rocket science it just needs to be explained properly. Java 'Direct Memory Byte Buffers'. Simple concept, described poorly!
    - kache_ 5y ago
      ahhhhhhhhhhhhh `g d` ;_;
Mizza 5y ago
I get the impression that there are many professional developers who have never actually seen good documentation at any point in their lives. So many organizations think that having all of the functions listed in on a Javadoc page is somehow the same thing as documentation. And they wonder why it takes a new developer months to become productive..
- FractalHQ 5y ago
  And then you have the common argument that comments are bad practice. If I can read 2 lines of comments for every 20 lines of code while navigating a large codebase until I find the code I really need to dive into, the productivity gains from that are nothing to scoff at.
  - twblalock 5y ago
    The downside is those two lines of comments might be outdated and no longer match the code they purport to document, which can mislead you into believing something incorrect about how the code functions. I've seen that happen a lot.
    - ShroudedNight 5y ago
      I'm more than half convinced that the comments shouldn't be in the code itself but attached as metadata to the commit that introduced the code in question, with the further implication that every commit should be focused around a single idea that lends itself to a single coherent narrative. The big drawback (right now?) is that diffs are computed on a line basis rather than a semantic token basis, so a bug fix for a comparison operator obfuscates the raison d'être of a whole conditional.
  - metamet 5y ago
    Writing self documenting code alongside comments makes things so easy on people who have to understand your code later on. I have gotten quite a few comments from former co-workers who have taken over some of the projects I was lead on about how easy it was to read. That brings me a lot of joy, knowing that I made their lives easier and that the output of the trade I invest so much time and energy into is appreciated by my peers.
eldelshell 5y ago
println
- dboreham 5y ago
  !
croo 5y ago
Isn't this the "hard part" of the job we are being paid for?
- mikewarot 5y ago
  We're being paid to do the work necessary to meet the goals set by management, and to provide useful feedback and guidance about what is/isn't possible, and how long it will take. If they (management) choose to ignore our guidance, or straddle us with bad tools, it sucks for us, and them, and the company.
  - bckr 5y ago
    Also, "the hard part" is understanding the system--therefore, shouldn't we optimize that part to make it less hard?
- hinkley 5y ago
  Parkour is a way to enter a building but if you expect other people to do it too, you’re off your gourd. If you insist on everyone else doing it, you’re a maniac. Too many maniacs in this industry.
deleted 5y ago
[deleted]
indymike 5y ago
There are three ways you can make an app easy for new developers to quickly be productive in... as long as deployment and code management tools are easy: * Coaching/Mentoring - Original developers there to help * Great documentation - App is documented, and it's easy to discover how it's put together * Great API / abstraction - The api or structure is really easy to understand and use - this is why REST beat out more sophisticated API models. Even so, it needs great documentation to be easy to learn and build with I think a lot of companies don't get any one of the three above right, so everything is very opaque. Also, you can't let tooling block developers from getting into understanding the code. New dev onboard times are a great way to measure this.
lizardactivist 5y ago
Using 3rd party software and libraries: spend hours flicking through documentation pages to find lots and lots of information, but no clarity.
- all2 5y ago
  For me, this activity is very often driven by "I need to do X, how do I do that?" It can be as general as "I want to make a web app with X language using Y framework". Often (for Golang and python, for example) there are lots of video tutorials talking about the necessary boilerplate -- so much boilerplate. It can also be extremely specific "I want to split a ReadOnlySpan<char> on some delimiter (which you can't do, you need to cast to a string and use the Split method there). Fortunately, that was an easy thing to find an answer for. Sometimes I want something specific that I have no clue how I would even start looking for the answer. I want to build a web app with a modular payment end-point so I can plug/play a large number of providers (ideally, I'd be able to arbitrarily hook in Stripe or the Bitcoin Lightning network or something else entirely). There are a host of problems for me here; I don't understand the problem space, so I have no clue what a "good" solution would look like, I don't even know if generic payment APIs even exist (zero research on my part), let alone in languages I understand (go, python, C#). I guess my issue is formulating questions appropriately, so that the sum of answers is an answer to my driving question "how do I do X?"
sssilver 5y ago
Figuring out existing bespoke systems is what sucked the joy of programming out of my soul.
- tudorgirba 5y ago
  I see this perspective too often. The good news is that it does not have to be painful :). Looking inside the system can be beautiful if only we change the tools through which we look.
  - sssilver 5y ago
    What are the right tools? I’d love to read about what I may be missing out on.
dep_b 5y ago
I spend about 60% of my non-meeting time fighting with broken tooling that was supposed to make my life easier.
- pjerem 5y ago
  Let me guess, 60% of this time fighting with broken tooling is in-house tooling. But I feel you. You are not alone.
gleenn 5y ago
People always struggle or avoid doing pair programming, and people always think it means that the developers' time now costs twice as much, but this is a total lie. When I worked at a place that did 100% pair programming with rotation every day, a new developer could hit the ground flying. Sitting next to someone who knows the system and can answer your question immediately means you get up to speed millions of times faster than screwing around by yourself. Pointed-haired bosses and accountants will never understand this. If you pair and rotate, the inexperienced person becomes experienced quickly, and it's viral if you also do rotating pairing. A team with one expert and pairing is now a team full of experts.
- visarga 5y ago
  > People always struggle or avoid doing pair programming Would using an improved Github Copilot be similar to pair programming but without the stress? Let's assume Copilot can understand whole projects not just single files, can do proper dialogue, is able to generate test cases and explain code.
- verve_rat 5y ago
  In my experience a team with one expert and pairing quickly becomes a team with many so-so members and an expert facing burnout.
- Veuxdo 5y ago
  You don't think this depends at all on the particulars of the developer(s)? E.g. their personalities, experience, skill level?
  - rednerrus 5y ago
    It seems counterproductive to have developers on your team who aren't capable of collaborating in this way.
    - Veuxdo 5y ago
      There's a chasm between "developer who always pair-programs all the time" and "developer who isn't capable of pair-programming".
newaccount2021 5y ago
FractalHQ 5y ago
I’ve always been fascinated by the glamorous toolkit project. Their ambitions are fascinating and align closely with software I’ve daydreamed about on more than one occasion. I wish I was more comfortable with lisp, or that it was compatible with Svelte/Typescript/Deno/Tauri which account for 90% of the projects I work on. I hope projects like this and Enso[0] are early iterations of what IDEs will look like in the future. There is so much room for innovation regarding ways to extend and augment the text formats used to author and represent software systems. [0]https://github.com/enso-org/enso https://github.com/enso-org/enso
- leobg 5y ago
  Thank you for pointing me to Enso. This looks amazing. For the others, here’s a video demo: https://youtu.be/fQvWMoOjmQk https://youtu.be/fQvWMoOjmQk
falcolas 5y ago
As someone trying to learn spring boot and lombak to write a complicated service... yeah, this. But I'm not just reading my code, I'm reading abstractions piled on abstractions. It's crazy. In the end I'll have to write less code, but I have to understand so much more just to write that "less code".
- teknopaul 5y ago
  Burn lombok with fire. Code you can't read, and cant debug, is horrible to work with. I find the best was to make your code grokable, is to have junit tests for everything that run fast in the ide. When code needs maintenance, you can run it in the debugger quickly and see what it actually does, instead of what it was intended to do. The worst Java code is lombok code that gets fsked by aop and/or hibernate. I call these abominations Nojos (not plain old java objects) Again: burn lombok with fire. Wrong line numbers, ungreppable code, obsure bugs, different depending on the lombok version 70% maintenance cost compared against, two seconds to have your ide automatically make explicit the code you are going to run.
zozbot234 5y ago
This sounds intuitively correct. It also leads to the unintuitive implication that paying down technical debt as soon as it arises and keeping systems simple and elegant as much as feasible, and well-documented wrt. inherent complexity, is not just key to software assurance and quality in general, but also to optimizing the use of developer time. Accidental complexity is not really manageable "debt"; it imposes large and growing costs over time.
- markburns 5y ago
  Couldn't agree more. Maybe one slight variation, that I think still agrees in principle, is considering 'the cost of doing this now vs cost of doing it later'. Sometimes technical debt is isolated and handling it can wait until the next time that code is touched. Often people may use this as an excuse. But there are a few cases where you can just wait and it won't be harder to fix later. I suppose this is the real form of debt that people should be referring to when they typically think of technical debt. It's debt with a next to zero percent interest rate. Just borrowing a bit of time now from future engineering time. A lot of technical debt that is left is the kind that carries a few thousand percent interest rates and can quickly tie an organisation in knots.
atum47 5y ago
Yep, once I spent the whole day reading code to write one single line of code at the end of the day. Since my boss is also a developer he understands. Try to explain that to a manager who doesn't write code thou...
stretchwithme 5y ago
You mean it's not like TV, where the code flows out of my fingertips for many lines and then magic happens?
- kingcharles 5y ago
  No, it's exactly like that for me. Personally, I code everything in vertical lines of green hex on a black background.
  - stretchwithme 5y ago
    You can't imagine how difficult that is to read when you check your code into github like that.
tromp 5y ago
> we should start by talking about how not to read code. We cannot afford not to. Nice triple negation there...
sam0x17 5y ago
This seems like a really, really good justification for the Rails Way of having a sane and predictable app file structure and layout where developers who have never seen your code before can jump in on day one and figure things out very quickly. Would love to see more web frameworks adopt this opinionated methodology to save us all some time.
- kingcharles 5y ago
  It's getting so far from the original web coding I did in 1995 where you had a .html file, to modern frameworks where 99% of the underlying code is in a hidden file nested 17 levels deep that is an interface to a virtual class that exists only in the imagination of the framework creator.
- Kerrick 5y ago
  That's one of the things I continue to love about the Ember.js framework.
- slotrans 5y ago
  The "Rails Way" doesn't work at all, and in fact hinders understanding, when a new developer doesn't know the Rails conventions. If you're happy to exist and hire within one ecosystem that can be fine. Otherwise it's disastrous.
  - sam0x17 5y ago
    The alternative is living in a microcosm of your own product/company, as the rest of the world is the wild west with no purported conventions at all. So even if it's a disaster, it's a better disaster than not having recognizable conventions that anyone outside of your company is aware of. And I say this as someone who originally live-edited PHP sites over FTP on apache in the early 00s. Convention is everything. Rails can be quite a disaster, but it has some solid conventions on app structure, routing, and security. It's not that Rails is great, it's that having conventions and sane defaults that get you somewhere instead of nowhere is better than not having them. No other major popular framework that I'm aware of has any real conventions on app structure or on any of the core things that 99% of apps need anyway, so everyone is out there re-inventing the wheel. In most frameworks, you get almost nothing included by default, and have to make key decisions on things like how will you encrypt cookies, how will you do CSRF protection, and sometimes even more basic things like how will you do routing. This has led to rampant security vulnerabilities reminiscent of the PHP days of yore imo. Productivity-wise this has made it impossible to get anything done, because the second you go to work for a new company, you end up having to help them re-implement basic processes like integration testing, CI, app structure, because everyone in the wild is just flying by the seat of their pants and making it up based on their limited experience and knowledge. "Oh, we just copy paste this boiler-plate and manually load SQL files for our migration system" "What's CSRF?" "What do you mean having separate environments for development, testing, staging, and production?" "Oh, we kept getting that CORS error so we just added a wildcard and it went away" etc etc
zwieback 5y ago
Question though: what about very stable codebases that are actively developed for a long time. My team maintains a couple SW projects (for internal manufacturing and equipment automation) with a core that has been stable for 10+ years. Once a developer is up to speed (3-6 months) that cost is recouped over several years. Of course this doesn't work for projects utilizing brand-new technology but it doesn't make sense to throw all types of projects into one pot. If there's a case to be made that mature code bases require less "figuring out time" then organizations should discourage jumping on the latest technology "just because".
- tudorgirba 5y ago
  Interesting. We find the situation to be quite the opposite. The older and larger the system, the more expensive figuring out is. You mention a 3-6 months. That's quite a high price. Would it be inconceivable to optimize this significantly? Stability can also be misleading. It's especially the small changes that can be problematic because when the code is large enough, people simply do not know what of what they already know (what's already in their memory) is no longer true. This is the challenge. Instead, the proposition is that we should not have to rely on our memory of things that can change. We can just check it. Only to do it in a reasonable timeframe, we need custom automation. In any case, the article does not propose a tool. It proposes a way of working. The tool is important to show how it can work in practice.
holoduke 5y ago
Developing is constant problem solving. Inside the app domain and also outside. Nothing new here. Someone claiming developing is possible only within the app domain is a fool.
davidw 5y ago
The older I get, the more important I think it is to get set up with a simple(ish) development environment where I can easily reproduce bugs, develop features and so on. This is one area where microservices can be a PITA if the dev environment hasn't had the same attention paid to it that the production environment has.
smm11 5y ago
Took me eight months at a government gig to figure out how the system worked - much less how it was set up, then I left three months later ...
giantg2 5y ago
In my experience, the biggest obstacle in understanding the system is that the underlying business process is not properly documented. A technical system is only as good as the business system it's implementing. Knowing the business process makes it much easier to understand the technical implementation, especially if you're trying to find bugs in the technical system since you can more easily see the mismatch between business and technical processes. But hey, that's just me. And it seems clear that most businesses do a poor job, or don't care at all, when it comes to documenting their processes. So I guess I'm the odd one.
- catmanjan 5y ago
  Yes, and given its not documented there are bugs in the underling business process which end up getting encoded into the software...
  - giantg2 5y ago
    Yes! And I love it when the business says they want to innovate, or improve efficiency, but they aren't willing to document and analyze the business process. Sure, we can implement your process as you communicate it to us, but I wouldn't call that innovative. Innovative would be modifying to process to take advantage of some new technology or model.
  - dvtrn 5y ago
    Conway’s law, holding on line 2.
- epolanski 5y ago
  Heavily agree. So many times rewriting a feature from scratch is faster than figuring out from code, and there is a lot of really hard to understand code out there. I remember once in a consultancy job for a bank having to maintain a form with a file uploader made of dozens and dozens redux actions interwhining in the most complex way one could imagine. There were atleast 4 folders of sagas. No one could understand the code, I fought it a few days before deciding to manually document its cases by trying all input combinations I could think of and just rewrote it fromscratch in less than 250 locs. Took me an afternoon to rewrite it and do the maintenance task. If I had e2es since the beginning I could've figured it out sooner..
azinman2 5y ago
I almost took a different path for my PhD and made it about capturing the knowledge that went into the creation of software. Can we see what people worked on, what they touched, how it came to be… in conjunction with the things they were also learning/consuming/reading/talking about so that we could bake that into IDEs. Right now we just see text files; the most we have is a git blame but you have to keep pulling the thread. It’s also very hard to traverse across blames in time. I’d rather use past knowledge to both know what’s related to some part, as well as how it came to be to determine where it should go next. I’ve always felt there’s meat on this bone. The early days of Lighthouse IDE seemed to veer a bit into this by they since diverged.
paulcole 5y ago
As a non-developer, this strikes me as funny. Like when Uber “invented” the bus. People who have knowledge-worker jobs and are halfway decent at them spend a lot of their time planning and making sense out of the systems they work in. Believe it or not, the oft-derided-on-HN MBAs and marketing people figure things out, too!
- tudorgirba 5y ago
  Interesting. Consider how the marketing work changed over the past decade to integrate data science. The amount of time spent on decision making might have not changed, but how the time is spent did change significantly. The article argues that the same thing should happen in software: developers should spend less time gathering information through data science and more time making decisions. This happens to change the nature of programming.
phyzix5761 5y ago
This only has an impact when we want to change a system. Coincidentally, the majority of our work is changing a system through addition of new functionality or maintenance. I've thought about this problem for a long time. The conclusion I've come to is that it happens because the code doesn't look like the domain. Domain language is often missing in the code the engineers are working with so when new changes are requested the engineer needs to translate between the domain language and the language the code is using. I work in an object oriented language so my perspective is as follows: Ideally, all that should be required is a correct domain understanding. If the objects in the code reflect the domain as understood and explained by the people giving the requirements then the engineer's job becomes easier. Instead of solving 2 problems, translation and engineering, they only need to focus on engineering. For example, imagine a payment system. A requirement comes in stating that the way a credit transaction in a payment is processed has changed. The transaction should now be processed by doing x, y, and z instead of a, b, and c. The engineer should be able to find an object in the code called a payment that has a credit transaction object with a method named process. Once they find this with a simple text search they know exactly where their change needs to happen. They should then see a, b, and c happening as explained in the domain language. Once this is identified the change can be performed. In reality, we seldom find domain objects with domain behavior in our code. What we find are Processor and Controller and Handler classes that have nothing to do with the domain. The behavior or data that we need to change is spread among multiple of these classes whose connection was arbitrarily decided by another engineer at a previous point. The new engineer has to work twice as hard to understand what decisions the previous engineer made to represent the domain. It's much easier at first to do this translation work because we don't want to, or have time to, understand the domain. But business domain experts are experts for a reason. They know how to solve business problems within their domain. We are not domain experts. So we end up reinventing the domain solution wheel when we do things this way. We end up solving the business problems and the engineering problems. Instead, we should see ourselves as modelers. Remember that computer science arose as a sub field of physics. The main purpose of physics is to develop models that represent the real world and solve problems using those models. Our job as software engineers is to model the domain and solve problems using those models. Our job is not to translate requirements into technical solutions. Nor is it to solve business problems.
CliffStoll 5y ago
Wow - is nobody else bothered by all the empty precision? 57.62% Comprehension, 23.96% Navigation... Even the piechart labeled "True effort required for many large-scale systems" says 7% of "effort" is Integration Test, and 8% in Module testing... Want to raise my hackles? Give me statements with lots of precision but lacking in documented (not to mention repeatable, reliable, or robust) accuracy. Convolved on this numeric silliness are several cartoons of smiling faces with vapid captions like "The figuring out time is a decision making time" or "Assessment is the process of understanding a situation around a system enough to make a decision".
- GnomeSaiyan 5y ago
  Can you explain like I'm 5? I'll be honest I have no idea what you're even trying to say here.
  - usefulcat 5y ago
    It’s a red flag when you see very precise numbers for things that are inherently difficult to measure.
  - tonyedgecombe 5y ago
    Precision != Accuracy.
- tudorgirba 5y ago
  Those numbers come from a peer-reviewed paper and it refers to the data they found in their specific experiment. It is not argued that those specific numbers appear in all cases. However, that data happens to be consistent with several other similar experiments done over the past 20+ years. The rest of the short article builds an arguments based on the assumption that at least 50% of the development time is spent figuring the system out. If you find this assumption to be off base, please disregard the rest of it. In any case, I'd encourage you to ask peer developers if they find that they spend 50% or more of their time reading textual artifacts as a way to figure the system out (code, logs etc).
epolanski 5y ago
> I see the flow of constructing custom tools during development, and, ideally, for every single development problem, as the next major leap in software development. I wish I could transmit this concept in my organization. 1) E2E tests as business requirements living documentation are the best first step any organization/project can make besides their tremendous technical value. At least remove the need from contributors to figure out business from code. 2) Confluence-like services cannot work as technical documentation. There's plenty of tools that allow you to generate docs from code, use them! We should lessen the friction from abstract to development,and that starts with providing good tools that bridge tge two.
- tudorgirba 5y ago
  Yes! This is one of the areas we actively explored and validated against. For example, take a look at: https://vimeo.com/498735070 https://vimeo.com/498735070
desertraven 5y ago
Regarding pair programming - I'm a self-taught freelancer based in a remote area (not many local devs). How might I bring about the benefits of pair-programming or even mentorship in a remote context? Mentor As A Service? Sounds a little lame to be honest.
- rpmisms 5y ago
  Work on a project remotely with another dev.
sebringj 5y ago
I have found that knowing the system is the most important thing over anything else. You end up being less wrong and have fantastic suggestions to the group on the direction and purpose of things or catch those edge cases when something is suggested or comes up that others don't know the consequences of or how it all connects together. This is where true value lies.
evilotto 5y ago
For an environment that's supposed to be about making things easier to discover, the glamorous toolkit website is pretty useless. Lots of bragging about how great it as, and lots of unreadable screenshots that do not interest me enough to actually download and install the thing.
- tudorgirba 5y ago
  The environment aims to make systems easier to grasp for people that want to explore their inside. This is quite different from the marketing challenge of convincing one to download a tool after a few seconds :).
  - evilotto 5y ago
    If this was say, an optimizing compiler, I wouldn't worry that much about their pitch. The tool is (from what little I could glean) supposed to make discoverability better. That suggests to me that they know something about how to make things discoverable, by bubbling up important information, hinting at where you want to go. The website was pretty much NOT that. Sure, maybe it's one of those "the shoemaker has the worst shoes" things. I'm interested, but not interested enough to work hard at figuring out what the thing is even supposed to to. If I want to work hard to explore the inside of a system, I can already do that.
- ivanche 5y ago
  What about these videos: https://vimeo.com/496004749 https://vimeo.com/496004749 and https://vimeo.com/498735070 https://vimeo.com/498735070?
SN76477 5y ago
I draw a lot of diagrams, everyone in my company seems to think I am nuts.
- tudorgirba 5y ago
  Do you draw them automatically, or manually?
  - SN76477 5y ago
    Manually
giraffe333 5y ago
One place I worked, the rule was "always have two pairs of eyes on code". Each team got to decide whether that rule was met with some mix of mob or pair programming, or just code reviews/pull requests. We could change depending on the needs of the project and team members. If management forces any of these options on teams it is a huge mistake. The point of pair programming is to share knowledge, reduce bugs, etc. and making it into a metric to measure teams by doesn't work. It's a lot like setting a minimum code coverage rule like 80 or 90%, people end up cursing the rule as it makes them do stupid things to satisfy the rule. Code coverage is one great tool to explore where your code needs more tests, but it's not the only one, and it's not the point. The point is writing code that's easily maintained, safely changed, and can be delivered to meet customer needs. You hired really smart people (hopefully) and you should let them decide how to work.
fuzzfactor 5y ago
Sometimes too much time is spent trying to avoid figuring it all out.
omgitsabird 5y ago
Then, not too long afterward, they forget everything.
aunty_helen 5y ago
24% navigation is why I love pycharm so much. I'd 1v1 anybody on a new python codebase for speed of navigation.
galaxyLogic 5y ago
This article seems like a motivational text for their tool: https://gtoolkit.com/ https://gtoolkit.com/ . Has anybody tried it?
- tudorgirba 5y ago
  Not quite. It's a motivational text for Moldable Development (https://moldabledevelopment.com https://moldabledevelopment.com). This is a way of programming through which programmers construct custom experiences for every single development problem. This is a significant departure from the typical development flow today, and Glamorous Toolkit is merely the arena in which to explore what is possible when thinking like this.
Pxtl 5y ago
Which is why as a code reviewer the legibility of the system is my top priority. I don't even care if the code works that'll come out in testing. I care if I can look at each section and understand what it's doing and why. And I'm utterly flabbergasted how many developers don't understand this.
- tudorgirba 5y ago
  Legibility is relevant. The problem is that legibility requires one to read. And one cannot read the whole code fast enough. That's why legibility is relevant in the small (~one screen). In the large, we can benefit greatly from other ways to summarize the system.
black_13 5y ago
nickysielicki 5y ago
This is why you should keep your system as normal as possible. Avoid custom workflows at all costs.
sachin_m 5y ago
The idea that “developers spend most of their time in reading and understanding the code” resonated with me, but the tool (gtoolkit) that this article is suggesting is too complex for me to understand and make it work. The tutorials or demos are about an hour long. I would appreciate if any tool can get me started in just 2-3 minutes (max) of hand holding. I don’t want to spend hours in a tool just to get started and then realizing that it will or not work for me.
- eBombzor 5y ago
  Spent about half an hour trying to understand what the heck the gt tool is. I have no prior experience of this and I just find it wildly abstract.
- t0suj4 5y ago
  Unfortunately, gtoolkit has pretty steep learning curve. And it's not different from Pharo gtoolkit is built on. I think there is a clash of concepts. It took me a lot of time getting used to the smalltalk workflow of experimenting in the playground and jumping into the editor to change things. It is very different from recompiling and restarting or from running a repl.
Annatar 5y ago
I have empirically determined that the main reason for this problem is the unwillingness to put in the effort to completely automate the work. The most often used argument I get is: it's not worth the effort to completely automate something that one has to perform maybe only once in six months or once per year. This argument is patently flawed and wrong, because it assumes that it's only worth automating something if it is done often enough. Scientifically, "often enough" isn't quantifiable, and that argument completely neglects the repeatability aspect: by fully automating, the steps to perform something are codified and quantified.
terbs 5y ago
Dang - from the way the article was written, I was really hoping to see some magic static code analyzer that would explain a system to a developer. But instead it looks like some enhanced version of Jupyter notebooks?
- tudorgirba 5y ago
  The proposition is not a tool, but an approach (moldable development). In a way, it is like data science, but for software. The approach was validated for more than a decade in industrial settings. Indeed, there is an environment involved to show how it can work in practice. It's understandable that one can see it as some kind of notebook, but it's really more than that. For example, there is a lot of emphasis on custom inspectors as basic pieces in the environment.
bumblebritches5 5y ago
sha_burn 5y ago
As a past customer, this is simply a great company with many Greenfields ahead in the space and some of the best leadership I've crossed in the Valley.
Silhouette 5y ago
Of course, for this to be practical, the cost of creating custom tools must be small. The doubtfulness of that axiom is why writing code that is easy to read and understand without special tools is so important.
- tudorgirba 5y ago
  The creation of tools can actually be minutes cheap. Through Moldable Development one creates such tools regularly, and most of these are thrown away after being used just once. That can sound like a waste, but it's a significant booster. It does require new skills though.
Dave3of5 5y ago
Then when they eventually do they get bored and move on.
navotgil 5y ago
The link is broken... anyone got a cached version or something?
progx 5y ago
Most of the time i feel i watch and learn new things, try to work with them, fail on some point, cause the new shiny things are not so shiny and easy as it seems. "The devil is in the details". Read article about how great these tools and libs are, how "easy", how they save so much time. Thinking about what i am doing wrong. Illusion. Self-deception. Try 1000 other libs and tools and frameworks and and and, repeat in an endless loop. My real productiv code is absolutly tiny compared to the huge amount of work i have and how much a permanently learn and educate myself.
zubairq 5y ago
I 100% agree with this. I would say that 99% of time is spent figuring the system out, and most maintenance time or new features time is just figuring out what is already going on.
jasfi 5y ago
That's why really well designed abstractions are so important, and leaky abstractions are a nightmare.
oddthink 5y ago
More on topic, I've experimented some with Glamorous Toolkit, and I really liked what I saw of it, but (somewhat ironically), I need to dive more into its own model and understand it before I can use it for anything real. For example, I couldn't find docs on its display stack, so when I wanted to display a graph but with images instead of text for the nodes, I got stuck. Sure, I could dive into the code and eventually get something that worked, but I wouldn't be sure I was coding to the API or to the implementation. It crossed over to "playing around with this tool" to "have to do some real work to understand", so I ended up dropping it.
- tudorgirba 5y ago
  I understand that it can feel uncomfortable to look into a system to know how to use it. However, Glamorous Toolkit is the first large case study of moldable development. To this end, there are custom little tools inside (some ~2k of them) that help you in this exploration. For example, one of the first things we encourage people to learn when they start with GT is how to query the GT code from within GT. Indeed, we are still to improve the onboarding experience. To this end, more recently, we added a book with live explanations. This is still a work in progress. That said, GT should be approached as a language. One can do as much with basic hello world exercises, but to extract more value one has to go into deeper details.

839 points by webmaven 5y ago

This matches my experience. IMO the best alternative tovreading code is to talk about the intent of the system by other coders or architects. Formulating questions is a start of understanding. Getting answers or directions increases understanding even more, for both parties.

Veuxdo 5y ago

Very true. In fact, this was the impetus behind my project. Over the decades there's been a ton of focus on machine learning and big data, but virtual none on human understanding [of systems].

deleted 5y ago
[deleted]
tudorgirba 5y ago
Do you have a link to your project?

bcbrown 5y ago

Relevant to this article is Peter Naur's paper on Programming as Theory building: https://pages.cs.wisc.edu/~remzi/Naur.pdf https://pages.cs.wisc.edu/~remzi/Naur.pdf He argues that the biggest determinant on whether maintainers on a system they did not build will succeed is whether they will have access to the original developers: "The conclusion seems inescapable that at least with certain kinds of large programs, the continued adaptation, modification, and correction of errors in them, is essentially dependent on a certain kind of knowledge possessed by a certain group of programmers who are closely and continuously connected with them."

wwweston 5y ago
See also Bill Thurston's commentary on the nature of mathematical knowledge: "mathematical understanding does not expand in a monotone direction. Our understanding frequently deteriorates as well. There are several obvious mechanisms of decay. The experts in a subject retire and die, or simply move on to other subjects and forget. Mathematics is commonly explained and recorded in symbolic and concrete forms that are easy to communicate, rather than in conceptual forms that are easy to understand once communicated. Translation in the direction conceptual -> concrete and symbolic is much easier than translation in the reverse direction, and symbolic forms often replaces the conceptual forms of understanding. And mathematical conventions and taken-for-granted knowledge change, so older texts may become hard to understand. In short, mathematics only exists in a living community of mathematicians that spreads understanding and breaths life into ideas both old and new." https://mathoverflow.net/questions/43690/whats-a-mathematician-to-do/44213#44213 https://mathoverflow.net/questions/43690/whats-a-mathematici...
- epolanski 5y ago
  I don't really buy that. Mathematics is by far the biggest and longest running open source project on this planet and we are absolutely able to traverse it by centuries or millenia. This works across languages and cultures. Mathematics is built on a small set of axioms and everything else is defined on top of it and proved. Your comment makes it sound like there is some magic knowledge linked to arcane symbols, when mathematicians are the least interested in symbols and labels, they care about definitions. As with any field if you get in highly specific topics then obviously you are going to lack enough literature and tradition on these topics and something may get lost, but if everyone forgot all they knew about math today we would be easily able to get back to where we are in a just by reading.
  - fantod 5y ago
    > if everyone forgot all they knew about math today we would be easily able to get back to where we are in a just by reading If your definition of "easily" is the amount of work required to become a mathematician, then sure.
MattGaiser 5y ago
A former colleague sent me an receipt that had an error from a system we worked on years ago (2 and 3 companies ago respectively). I bet we could tell the current devs where to find the bug pretty easily as we wrote a lot of that code.
cloogshicer 5y ago
That paper is amazing. Completely changed my view on programming. For those who find it a bit inaccessible (as I did on my first read), I wrote an article about it a while back, explaining it further and giving real-life examples: https://hiringengineersbook.com/post/autonomy/ https://hiringengineersbook.com/post/autonomy/
- mehphp 5y ago
  Well that was a great read; thanks for sharing!
- ilovecaching 5y ago
  Nice article, I enjoyed reading it.
  - cloogshicer 5y ago
    Thanks! :-)
- mikewarot 5y ago
  >The main value of a software company is the mapping of source code and problem space in the developer’s heads [In linked article] That is a profound conclusion to reach. For the most part, I think it's true. Without someone who wrote/fully understands source code, for example in abandoned software, the source code is a treasure map, the as-built plan of a building. It takes a lot of time and effort to orient yourself with things and make reasonable guesses as to what is going on. This aligns well with the original post.
magicalhippo 5y ago
We see something similar with our customers. When our customers have some new projects or change their ERP or whatever, we almost always know better than they do how their systems and procedures work. Like, if they come with a change request we might ask what about X, they'll get all surprised saying no we don't do X, but after a bit of prodding sure enough, they discover they have a worker that's handling X every day. This is simply because we've been around, while they've had multiple new persons cycle through their departments. When they change the ERP system, we've still got the guy who coded the integrations with their previous system.
amatecha 5y ago
Text version of that article: https://gist.github.com/onlurking/fc5c81d18cfce9ff81bc968a7f342fb1 https://gist.github.com/onlurking/fc5c81d18cfce9ff81bc968a7f...

mooreds 5y ago

Haha, so true! I've found that for most systems, there are three great ways to "figure it out". * Start from input. (Browser, API, whatever starts a process.) Map from there. * Start from data storage. (Database, flat files, whatever.) How does state get persisted? * How does the system move into production? If you can make a small change (even adding an innocuous comment) and see it all the way from your machine to prod, you can iterate and start to map the system.

samspenc 5y ago
A couple of things I found helpful along those lines: * Data storage: what does the schema look like? Even if it is not persisted to a relational DB, is it possible to draw out a schema of a data model and all the relationships ("JOINS") * Add logging to code you are trying to debug but are hard to understand and repro bugs for in production. Once you have logs about the full state that reproduces the error, the issue will be easier to fix. Don't roll out a fix before fully understanding an issue. As a corollary to this: always add a task to remove this verbose logging you added once the bug is fixed!
- bckr 5y ago
  > Add logging to code you are trying to debug This is a great idea and should absolutely be a standard. There's a whole logging level ("DEBUG") devoted to this that I think goes way underused. Another, related idea is to use a debugger. Using PDB for Python codebases has sped me up A LOT.
  - nine_k 5y ago
    I worked with software where you could change logging level dynamically, per subsystem. The ability to switch to DEBUG level, get a wall of text from a problematic spot, and switch it back to WARN was very, very helpful for troubleshooting prod.
selectronics 5y ago
Chiming in that this applies to controls engineering as well (think PLCs). Start from the IO, cross-reference that through the rest to get a feel of chains of causality and how it all works. Oftentimes it's critical to go from zero to applying changes as quickly as possible when unfamiliar (and poorly documented!) machinery is down.

jollybean 5y ago

It's why good abstraction and documentation for it is so powerful - you only need to understand the API and not anything else. We start teaching about software like it's 'algorithms' when that is frankly, almost pedantic. That was never the hard part. Scaling the complexity was always the hard part. Simple, clear code, absent leaky abstractions, enough documentation etc..

kache_ 5y ago
The problem with abstractions is that it seems that not making leaky abstractions is difficult for most people (most people making these abstractions don't know about the concept of an abstraction leakage in the first place) Software engineering is extremely difficult
- jollybean 5y ago
  That they don't even teach 'leaky abstractions' is a bit rich, and as you point out it's hard. And it's not 'hard for most people' it's hard for everyone. Every API is leaky and inconsistent, it's all a matter of degrees. Concise documentation is essential. I'm reading about a Java API for the 5th time and only now just 'getting it' fairy clearly, it's not rocket science it just needs to be explained properly. Java 'Direct Memory Byte Buffers'. Simple concept, described poorly!
  - kache_ 5y ago
    ahhhhhhhhhhhhh `g d` ;_;

Mizza 5y ago

I get the impression that there are many professional developers who have never actually seen good documentation at any point in their lives. So many organizations think that having all of the functions listed in on a Javadoc page is somehow the same thing as documentation. And they wonder why it takes a new developer months to become productive..

FractalHQ 5y ago
And then you have the common argument that comments are bad practice. If I can read 2 lines of comments for every 20 lines of code while navigating a large codebase until I find the code I really need to dive into, the productivity gains from that are nothing to scoff at.
- twblalock 5y ago
  The downside is those two lines of comments might be outdated and no longer match the code they purport to document, which can mislead you into believing something incorrect about how the code functions. I've seen that happen a lot.
  - ShroudedNight 5y ago
    I'm more than half convinced that the comments shouldn't be in the code itself but attached as metadata to the commit that introduced the code in question, with the further implication that every commit should be focused around a single idea that lends itself to a single coherent narrative. The big drawback (right now?) is that diffs are computed on a line basis rather than a semantic token basis, so a bug fix for a comparison operator obfuscates the raison d'être of a whole conditional.
- metamet 5y ago
  Writing self documenting code alongside comments makes things so easy on people who have to understand your code later on. I have gotten quite a few comments from former co-workers who have taken over some of the projects I was lead on about how easy it was to read. That brings me a lot of joy, knowing that I made their lives easier and that the output of the trade I invest so much time and energy into is appreciated by my peers.

eldelshell 5y ago

println

dboreham 5y ago
!

croo 5y ago

Isn't this the "hard part" of the job we are being paid for?

mikewarot 5y ago
We're being paid to do the work necessary to meet the goals set by management, and to provide useful feedback and guidance about what is/isn't possible, and how long it will take. If they (management) choose to ignore our guidance, or straddle us with bad tools, it sucks for us, and them, and the company.
- bckr 5y ago
  Also, "the hard part" is understanding the system--therefore, shouldn't we optimize that part to make it less hard?
hinkley 5y ago
Parkour is a way to enter a building but if you expect other people to do it too, you’re off your gourd. If you insist on everyone else doing it, you’re a maniac. Too many maniacs in this industry.

deleted 5y ago

[deleted]

indymike 5y ago

There are three ways you can make an app easy for new developers to quickly be productive in... as long as deployment and code management tools are easy: * Coaching/Mentoring - Original developers there to help * Great documentation - App is documented, and it's easy to discover how it's put together * Great API / abstraction - The api or structure is really easy to understand and use - this is why REST beat out more sophisticated API models. Even so, it needs great documentation to be easy to learn and build with I think a lot of companies don't get any one of the three above right, so everything is very opaque. Also, you can't let tooling block developers from getting into understanding the code. New dev onboard times are a great way to measure this.

lizardactivist 5y ago

Using 3rd party software and libraries: spend hours flicking through documentation pages to find lots and lots of information, but no clarity.

all2 5y ago
For me, this activity is very often driven by "I need to do X, how do I do that?" It can be as general as "I want to make a web app with X language using Y framework". Often (for Golang and python, for example) there are lots of video tutorials talking about the necessary boilerplate -- so much boilerplate. It can also be extremely specific "I want to split a ReadOnlySpan<char> on some delimiter (which you can't do, you need to cast to a string and use the Split method there). Fortunately, that was an easy thing to find an answer for. Sometimes I want something specific that I have no clue how I would even start looking for the answer. I want to build a web app with a modular payment end-point so I can plug/play a large number of providers (ideally, I'd be able to arbitrarily hook in Stripe or the Bitcoin Lightning network or something else entirely). There are a host of problems for me here; I don't understand the problem space, so I have no clue what a "good" solution would look like, I don't even know if generic payment APIs even exist (zero research on my part), let alone in languages I understand (go, python, C#). I guess my issue is formulating questions appropriately, so that the sum of answers is an answer to my driving question "how do I do X?"

sssilver 5y ago

Figuring out existing bespoke systems is what sucked the joy of programming out of my soul.

tudorgirba 5y ago
I see this perspective too often. The good news is that it does not have to be painful :). Looking inside the system can be beautiful if only we change the tools through which we look.
- sssilver 5y ago
  What are the right tools? I’d love to read about what I may be missing out on.

dep_b 5y ago

I spend about 60% of my non-meeting time fighting with broken tooling that was supposed to make my life easier.

pjerem 5y ago
Let me guess, 60% of this time fighting with broken tooling is in-house tooling. But I feel you. You are not alone.

gleenn 5y ago

People always struggle or avoid doing pair programming, and people always think it means that the developers' time now costs twice as much, but this is a total lie. When I worked at a place that did 100% pair programming with rotation every day, a new developer could hit the ground flying. Sitting next to someone who knows the system and can answer your question immediately means you get up to speed millions of times faster than screwing around by yourself. Pointed-haired bosses and accountants will never understand this. If you pair and rotate, the inexperienced person becomes experienced quickly, and it's viral if you also do rotating pairing. A team with one expert and pairing is now a team full of experts.

visarga 5y ago
> People always struggle or avoid doing pair programming Would using an improved Github Copilot be similar to pair programming but without the stress? Let's assume Copilot can understand whole projects not just single files, can do proper dialogue, is able to generate test cases and explain code.
verve_rat 5y ago
In my experience a team with one expert and pairing quickly becomes a team with many so-so members and an expert facing burnout.
Veuxdo 5y ago
You don't think this depends at all on the particulars of the developer(s)? E.g. their personalities, experience, skill level?
- rednerrus 5y ago
  It seems counterproductive to have developers on your team who aren't capable of collaborating in this way.
  - Veuxdo 5y ago
    There's a chasm between "developer who always pair-programs all the time" and "developer who isn't capable of pair-programming".

newaccount2021 5y ago

FractalHQ 5y ago

I’ve always been fascinated by the glamorous toolkit project. Their ambitions are fascinating and align closely with software I’ve daydreamed about on more than one occasion. I wish I was more comfortable with lisp, or that it was compatible with Svelte/Typescript/Deno/Tauri which account for 90% of the projects I work on. I hope projects like this and Enso[0] are early iterations of what IDEs will look like in the future. There is so much room for innovation regarding ways to extend and augment the text formats used to author and represent software systems. [0]https://github.com/enso-org/enso https://github.com/enso-org/enso

leobg 5y ago
Thank you for pointing me to Enso. This looks amazing. For the others, here’s a video demo: https://youtu.be/fQvWMoOjmQk https://youtu.be/fQvWMoOjmQk

falcolas 5y ago

As someone trying to learn spring boot and lombak to write a complicated service... yeah, this. But I'm not just reading my code, I'm reading abstractions piled on abstractions. It's crazy. In the end I'll have to write less code, but I have to understand so much more just to write that "less code".

teknopaul 5y ago
Burn lombok with fire. Code you can't read, and cant debug, is horrible to work with. I find the best was to make your code grokable, is to have junit tests for everything that run fast in the ide. When code needs maintenance, you can run it in the debugger quickly and see what it actually does, instead of what it was intended to do. The worst Java code is lombok code that gets fsked by aop and/or hibernate. I call these abominations Nojos (not plain old java objects) Again: burn lombok with fire. Wrong line numbers, ungreppable code, obsure bugs, different depending on the lombok version 70% maintenance cost compared against, two seconds to have your ide automatically make explicit the code you are going to run.

zozbot234 5y ago

This sounds intuitively correct. It also leads to the unintuitive implication that paying down technical debt as soon as it arises and keeping systems simple and elegant as much as feasible, and well-documented wrt. inherent complexity, is not just key to software assurance and quality in general, but also to optimizing the use of developer time. Accidental complexity is not really manageable "debt"; it imposes large and growing costs over time.

markburns 5y ago
Couldn't agree more. Maybe one slight variation, that I think still agrees in principle, is considering 'the cost of doing this now vs cost of doing it later'. Sometimes technical debt is isolated and handling it can wait until the next time that code is touched. Often people may use this as an excuse. But there are a few cases where you can just wait and it won't be harder to fix later. I suppose this is the real form of debt that people should be referring to when they typically think of technical debt. It's debt with a next to zero percent interest rate. Just borrowing a bit of time now from future engineering time. A lot of technical debt that is left is the kind that carries a few thousand percent interest rates and can quickly tie an organisation in knots.

atum47 5y ago

Yep, once I spent the whole day reading code to write one single line of code at the end of the day. Since my boss is also a developer he understands. Try to explain that to a manager who doesn't write code thou...

stretchwithme 5y ago

You mean it's not like TV, where the code flows out of my fingertips for many lines and then magic happens?

kingcharles 5y ago
No, it's exactly like that for me. Personally, I code everything in vertical lines of green hex on a black background.
- stretchwithme 5y ago
  You can't imagine how difficult that is to read when you check your code into github like that.

tromp 5y ago

> we should start by talking about how not to read code. We cannot afford not to. Nice triple negation there...

sam0x17 5y ago

This seems like a really, really good justification for the Rails Way of having a sane and predictable app file structure and layout where developers who have never seen your code before can jump in on day one and figure things out very quickly. Would love to see more web frameworks adopt this opinionated methodology to save us all some time.

kingcharles 5y ago
It's getting so far from the original web coding I did in 1995 where you had a .html file, to modern frameworks where 99% of the underlying code is in a hidden file nested 17 levels deep that is an interface to a virtual class that exists only in the imagination of the framework creator.
Kerrick 5y ago
That's one of the things I continue to love about the Ember.js framework.
slotrans 5y ago
The "Rails Way" doesn't work at all, and in fact hinders understanding, when a new developer doesn't know the Rails conventions. If you're happy to exist and hire within one ecosystem that can be fine. Otherwise it's disastrous.
- sam0x17 5y ago
  The alternative is living in a microcosm of your own product/company, as the rest of the world is the wild west with no purported conventions at all. So even if it's a disaster, it's a better disaster than not having recognizable conventions that anyone outside of your company is aware of. And I say this as someone who originally live-edited PHP sites over FTP on apache in the early 00s. Convention is everything. Rails can be quite a disaster, but it has some solid conventions on app structure, routing, and security. It's not that Rails is great, it's that having conventions and sane defaults that get you somewhere instead of nowhere is better than not having them. No other major popular framework that I'm aware of has any real conventions on app structure or on any of the core things that 99% of apps need anyway, so everyone is out there re-inventing the wheel. In most frameworks, you get almost nothing included by default, and have to make key decisions on things like how will you encrypt cookies, how will you do CSRF protection, and sometimes even more basic things like how will you do routing. This has led to rampant security vulnerabilities reminiscent of the PHP days of yore imo. Productivity-wise this has made it impossible to get anything done, because the second you go to work for a new company, you end up having to help them re-implement basic processes like integration testing, CI, app structure, because everyone in the wild is just flying by the seat of their pants and making it up based on their limited experience and knowledge. "Oh, we just copy paste this boiler-plate and manually load SQL files for our migration system" "What's CSRF?" "What do you mean having separate environments for development, testing, staging, and production?" "Oh, we kept getting that CORS error so we just added a wildcard and it went away" etc etc

zwieback 5y ago

Question though: what about very stable codebases that are actively developed for a long time. My team maintains a couple SW projects (for internal manufacturing and equipment automation) with a core that has been stable for 10+ years. Once a developer is up to speed (3-6 months) that cost is recouped over several years. Of course this doesn't work for projects utilizing brand-new technology but it doesn't make sense to throw all types of projects into one pot. If there's a case to be made that mature code bases require less "figuring out time" then organizations should discourage jumping on the latest technology "just because".

tudorgirba 5y ago
Interesting. We find the situation to be quite the opposite. The older and larger the system, the more expensive figuring out is. You mention a 3-6 months. That's quite a high price. Would it be inconceivable to optimize this significantly? Stability can also be misleading. It's especially the small changes that can be problematic because when the code is large enough, people simply do not know what of what they already know (what's already in their memory) is no longer true. This is the challenge. Instead, the proposition is that we should not have to rely on our memory of things that can change. We can just check it. Only to do it in a reasonable timeframe, we need custom automation. In any case, the article does not propose a tool. It proposes a way of working. The tool is important to show how it can work in practice.

holoduke 5y ago

Developing is constant problem solving. Inside the app domain and also outside. Nothing new here. Someone claiming developing is possible only within the app domain is a fool.

davidw 5y ago

The older I get, the more important I think it is to get set up with a simple(ish) development environment where I can easily reproduce bugs, develop features and so on. This is one area where microservices can be a PITA if the dev environment hasn't had the same attention paid to it that the production environment has.

smm11 5y ago

Took me eight months at a government gig to figure out how the system worked - much less how it was set up, then I left three months later ...

giantg2 5y ago

In my experience, the biggest obstacle in understanding the system is that the underlying business process is not properly documented. A technical system is only as good as the business system it's implementing. Knowing the business process makes it much easier to understand the technical implementation, especially if you're trying to find bugs in the technical system since you can more easily see the mismatch between business and technical processes. But hey, that's just me. And it seems clear that most businesses do a poor job, or don't care at all, when it comes to documenting their processes. So I guess I'm the odd one.

catmanjan 5y ago
Yes, and given its not documented there are bugs in the underling business process which end up getting encoded into the software...
- giantg2 5y ago
  Yes! And I love it when the business says they want to innovate, or improve efficiency, but they aren't willing to document and analyze the business process. Sure, we can implement your process as you communicate it to us, but I wouldn't call that innovative. Innovative would be modifying to process to take advantage of some new technology or model.
- dvtrn 5y ago
  Conway’s law, holding on line 2.
epolanski 5y ago
Heavily agree. So many times rewriting a feature from scratch is faster than figuring out from code, and there is a lot of really hard to understand code out there. I remember once in a consultancy job for a bank having to maintain a form with a file uploader made of dozens and dozens redux actions interwhining in the most complex way one could imagine. There were atleast 4 folders of sagas. No one could understand the code, I fought it a few days before deciding to manually document its cases by trying all input combinations I could think of and just rewrote it fromscratch in less than 250 locs. Took me an afternoon to rewrite it and do the maintenance task. If I had e2es since the beginning I could've figured it out sooner..

azinman2 5y ago

I almost took a different path for my PhD and made it about capturing the knowledge that went into the creation of software. Can we see what people worked on, what they touched, how it came to be… in conjunction with the things they were also learning/consuming/reading/talking about so that we could bake that into IDEs. Right now we just see text files; the most we have is a git blame but you have to keep pulling the thread. It’s also very hard to traverse across blames in time. I’d rather use past knowledge to both know what’s related to some part, as well as how it came to be to determine where it should go next. I’ve always felt there’s meat on this bone. The early days of Lighthouse IDE seemed to veer a bit into this by they since diverged.

paulcole 5y ago

As a non-developer, this strikes me as funny. Like when Uber “invented” the bus. People who have knowledge-worker jobs and are halfway decent at them spend a lot of their time planning and making sense out of the systems they work in. Believe it or not, the oft-derided-on-HN MBAs and marketing people figure things out, too!

tudorgirba 5y ago
Interesting. Consider how the marketing work changed over the past decade to integrate data science. The amount of time spent on decision making might have not changed, but how the time is spent did change significantly. The article argues that the same thing should happen in software: developers should spend less time gathering information through data science and more time making decisions. This happens to change the nature of programming.

phyzix5761 5y ago

This only has an impact when we want to change a system. Coincidentally, the majority of our work is changing a system through addition of new functionality or maintenance. I've thought about this problem for a long time. The conclusion I've come to is that it happens because the code doesn't look like the domain. Domain language is often missing in the code the engineers are working with so when new changes are requested the engineer needs to translate between the domain language and the language the code is using. I work in an object oriented language so my perspective is as follows: Ideally, all that should be required is a correct domain understanding. If the objects in the code reflect the domain as understood and explained by the people giving the requirements then the engineer's job becomes easier. Instead of solving 2 problems, translation and engineering, they only need to focus on engineering. For example, imagine a payment system. A requirement comes in stating that the way a credit transaction in a payment is processed has changed. The transaction should now be processed by doing x, y, and z instead of a, b, and c. The engineer should be able to find an object in the code called a payment that has a credit transaction object with a method named process. Once they find this with a simple text search they know exactly where their change needs to happen. They should then see a, b, and c happening as explained in the domain language. Once this is identified the change can be performed. In reality, we seldom find domain objects with domain behavior in our code. What we find are Processor and Controller and Handler classes that have nothing to do with the domain. The behavior or data that we need to change is spread among multiple of these classes whose connection was arbitrarily decided by another engineer at a previous point. The new engineer has to work twice as hard to understand what decisions the previous engineer made to represent the domain. It's much easier at first to do this translation work because we don't want to, or have time to, understand the domain. But business domain experts are experts for a reason. They know how to solve business problems within their domain. We are not domain experts. So we end up reinventing the domain solution wheel when we do things this way. We end up solving the business problems and the engineering problems. Instead, we should see ourselves as modelers. Remember that computer science arose as a sub field of physics. The main purpose of physics is to develop models that represent the real world and solve problems using those models. Our job as software engineers is to model the domain and solve problems using those models. Our job is not to translate requirements into technical solutions. Nor is it to solve business problems.

CliffStoll 5y ago

Wow - is nobody else bothered by all the empty precision? 57.62% Comprehension, 23.96% Navigation... Even the piechart labeled "True effort required for many large-scale systems" says 7% of "effort" is Integration Test, and 8% in Module testing... Want to raise my hackles? Give me statements with lots of precision but lacking in documented (not to mention repeatable, reliable, or robust) accuracy. Convolved on this numeric silliness are several cartoons of smiling faces with vapid captions like "The figuring out time is a decision making time" or "Assessment is the process of understanding a situation around a system enough to make a decision".

GnomeSaiyan 5y ago
Can you explain like I'm 5? I'll be honest I have no idea what you're even trying to say here.
- usefulcat 5y ago
  It’s a red flag when you see very precise numbers for things that are inherently difficult to measure.
- tonyedgecombe 5y ago
  Precision != Accuracy.
tudorgirba 5y ago
Those numbers come from a peer-reviewed paper and it refers to the data they found in their specific experiment. It is not argued that those specific numbers appear in all cases. However, that data happens to be consistent with several other similar experiments done over the past 20+ years. The rest of the short article builds an arguments based on the assumption that at least 50% of the development time is spent figuring the system out. If you find this assumption to be off base, please disregard the rest of it. In any case, I'd encourage you to ask peer developers if they find that they spend 50% or more of their time reading textual artifacts as a way to figure the system out (code, logs etc).

epolanski 5y ago

> I see the flow of constructing custom tools during development, and, ideally, for every single development problem, as the next major leap in software development. I wish I could transmit this concept in my organization. 1) E2E tests as business requirements living documentation are the best first step any organization/project can make besides their tremendous technical value. At least remove the need from contributors to figure out business from code. 2) Confluence-like services cannot work as technical documentation. There's plenty of tools that allow you to generate docs from code, use them! We should lessen the friction from abstract to development,and that starts with providing good tools that bridge tge two.

tudorgirba 5y ago
Yes! This is one of the areas we actively explored and validated against. For example, take a look at: https://vimeo.com/498735070 https://vimeo.com/498735070

desertraven 5y ago

Regarding pair programming - I'm a self-taught freelancer based in a remote area (not many local devs). How might I bring about the benefits of pair-programming or even mentorship in a remote context? Mentor As A Service? Sounds a little lame to be honest.

rpmisms 5y ago
Work on a project remotely with another dev.

sebringj 5y ago

I have found that knowing the system is the most important thing over anything else. You end up being less wrong and have fantastic suggestions to the group on the direction and purpose of things or catch those edge cases when something is suggested or comes up that others don't know the consequences of or how it all connects together. This is where true value lies.

evilotto 5y ago

For an environment that's supposed to be about making things easier to discover, the glamorous toolkit website is pretty useless. Lots of bragging about how great it as, and lots of unreadable screenshots that do not interest me enough to actually download and install the thing.

tudorgirba 5y ago
The environment aims to make systems easier to grasp for people that want to explore their inside. This is quite different from the marketing challenge of convincing one to download a tool after a few seconds :).
- evilotto 5y ago
  If this was say, an optimizing compiler, I wouldn't worry that much about their pitch. The tool is (from what little I could glean) supposed to make discoverability better. That suggests to me that they know something about how to make things discoverable, by bubbling up important information, hinting at where you want to go. The website was pretty much NOT that. Sure, maybe it's one of those "the shoemaker has the worst shoes" things. I'm interested, but not interested enough to work hard at figuring out what the thing is even supposed to to. If I want to work hard to explore the inside of a system, I can already do that.
ivanche 5y ago
What about these videos: https://vimeo.com/496004749 https://vimeo.com/496004749 and https://vimeo.com/498735070 https://vimeo.com/498735070?

SN76477 5y ago

I draw a lot of diagrams, everyone in my company seems to think I am nuts.

tudorgirba 5y ago
Do you draw them automatically, or manually?
- SN76477 5y ago
  Manually

giraffe333 5y ago

One place I worked, the rule was "always have two pairs of eyes on code". Each team got to decide whether that rule was met with some mix of mob or pair programming, or just code reviews/pull requests. We could change depending on the needs of the project and team members. If management forces any of these options on teams it is a huge mistake. The point of pair programming is to share knowledge, reduce bugs, etc. and making it into a metric to measure teams by doesn't work. It's a lot like setting a minimum code coverage rule like 80 or 90%, people end up cursing the rule as it makes them do stupid things to satisfy the rule. Code coverage is one great tool to explore where your code needs more tests, but it's not the only one, and it's not the point. The point is writing code that's easily maintained, safely changed, and can be delivered to meet customer needs. You hired really smart people (hopefully) and you should let them decide how to work.

fuzzfactor 5y ago

Sometimes too much time is spent trying to avoid figuring it all out.

omgitsabird 5y ago

Then, not too long afterward, they forget everything.

aunty_helen 5y ago

24% navigation is why I love pycharm so much. I'd 1v1 anybody on a new python codebase for speed of navigation.

galaxyLogic 5y ago

This article seems like a motivational text for their tool: https://gtoolkit.com/ https://gtoolkit.com/ . Has anybody tried it?

tudorgirba 5y ago
Not quite. It's a motivational text for Moldable Development (https://moldabledevelopment.com https://moldabledevelopment.com). This is a way of programming through which programmers construct custom experiences for every single development problem. This is a significant departure from the typical development flow today, and Glamorous Toolkit is merely the arena in which to explore what is possible when thinking like this.

Pxtl 5y ago

Which is why as a code reviewer the legibility of the system is my top priority. I don't even care if the code works that'll come out in testing. I care if I can look at each section and understand what it's doing and why. And I'm utterly flabbergasted how many developers don't understand this.

tudorgirba 5y ago
Legibility is relevant. The problem is that legibility requires one to read. And one cannot read the whole code fast enough. That's why legibility is relevant in the small (~one screen). In the large, we can benefit greatly from other ways to summarize the system.

black_13 5y ago

nickysielicki 5y ago

This is why you should keep your system as normal as possible. Avoid custom workflows at all costs.

sachin_m 5y ago

The idea that “developers spend most of their time in reading and understanding the code” resonated with me, but the tool (gtoolkit) that this article is suggesting is too complex for me to understand and make it work. The tutorials or demos are about an hour long. I would appreciate if any tool can get me started in just 2-3 minutes (max) of hand holding. I don’t want to spend hours in a tool just to get started and then realizing that it will or not work for me.

eBombzor 5y ago
Spent about half an hour trying to understand what the heck the gt tool is. I have no prior experience of this and I just find it wildly abstract.
t0suj4 5y ago
Unfortunately, gtoolkit has pretty steep learning curve. And it's not different from Pharo gtoolkit is built on. I think there is a clash of concepts. It took me a lot of time getting used to the smalltalk workflow of experimenting in the playground and jumping into the editor to change things. It is very different from recompiling and restarting or from running a repl.

Annatar 5y ago

I have empirically determined that the main reason for this problem is the unwillingness to put in the effort to completely automate the work. The most often used argument I get is: it's not worth the effort to completely automate something that one has to perform maybe only once in six months or once per year. This argument is patently flawed and wrong, because it assumes that it's only worth automating something if it is done often enough. Scientifically, "often enough" isn't quantifiable, and that argument completely neglects the repeatability aspect: by fully automating, the steps to perform something are codified and quantified.

terbs 5y ago

Dang - from the way the article was written, I was really hoping to see some magic static code analyzer that would explain a system to a developer. But instead it looks like some enhanced version of Jupyter notebooks?

tudorgirba 5y ago
The proposition is not a tool, but an approach (moldable development). In a way, it is like data science, but for software. The approach was validated for more than a decade in industrial settings. Indeed, there is an environment involved to show how it can work in practice. It's understandable that one can see it as some kind of notebook, but it's really more than that. For example, there is a lot of emphasis on custom inspectors as basic pieces in the environment.

bumblebritches5 5y ago

sha_burn 5y ago

As a past customer, this is simply a great company with many Greenfields ahead in the space and some of the best leadership I've crossed in the Valley.

Silhouette 5y ago

Of course, for this to be practical, the cost of creating custom tools must be small. The doubtfulness of that axiom is why writing code that is easy to read and understand without special tools is so important.

tudorgirba 5y ago
The creation of tools can actually be minutes cheap. Through Moldable Development one creates such tools regularly, and most of these are thrown away after being used just once. That can sound like a waste, but it's a significant booster. It does require new skills though.

Dave3of5 5y ago

Then when they eventually do they get bored and move on.

navotgil 5y ago

The link is broken... anyone got a cached version or something?

progx 5y ago

Most of the time i feel i watch and learn new things, try to work with them, fail on some point, cause the new shiny things are not so shiny and easy as it seems. "The devil is in the details". Read article about how great these tools and libs are, how "easy", how they save so much time. Thinking about what i am doing wrong. Illusion. Self-deception. Try 1000 other libs and tools and frameworks and and and, repeat in an endless loop. My real productiv code is absolutly tiny compared to the huge amount of work i have and how much a permanently learn and educate myself.

zubairq 5y ago

I 100% agree with this. I would say that 99% of time is spent figuring the system out, and most maintenance time or new features time is just figuring out what is already going on.

jasfi 5y ago

That's why really well designed abstractions are so important, and leaky abstractions are a nightmare.

oddthink 5y ago

More on topic, I've experimented some with Glamorous Toolkit, and I really liked what I saw of it, but (somewhat ironically), I need to dive more into its own model and understand it before I can use it for anything real. For example, I couldn't find docs on its display stack, so when I wanted to display a graph but with images instead of text for the nodes, I got stuck. Sure, I could dive into the code and eventually get something that worked, but I wouldn't be sure I was coding to the API or to the implementation. It crossed over to "playing around with this tool" to "have to do some real work to understand", so I ended up dropping it.

tudorgirba 5y ago
I understand that it can feel uncomfortable to look into a system to know how to use it. However, Glamorous Toolkit is the first large case study of moldable development. To this end, there are custom little tools inside (some ~2k of them) that help you in this exploration. For example, one of the first things we encourage people to learn when they start with GT is how to query the GT code from within GT. Indeed, we are still to improve the onboarding experience. To this end, more recently, we added a book with live explanations. This is still a work in progress. That said, GT should be approached as a language. One can do as much with basic hello world exercises, but to extract more value one has to go into deeper details.