Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 8 years ago.
Improve this question
I use JSDoc to document all the JS I write, but I am curious about how people document their less. I guess I could use JSDoc, but it doesn't seem right since less is not JS. I also want to avoid documenting my less with JSDoc if there is a standard way that might allow different IDEs to provide tooling support.
Does anyone know of a standard way of documenting less?
Documenting source code involves different issues, and may have different objectives, than documenting CSS, be it LESS or any other variant.
Source code involves classes and methods involving contracts, such as the types and meaning of parameters and return values. It also may have complex logic that requires explanation, or handle multiple conditions, or deal with various edge cases. It may be implementing an API which third parties will consume, which should have its own stand-along documentation that can be "read". Systems such as JSDoc are designed with all this in mind. People reading the code can easily understand the purpose and signature and logic of the various routines, and the comments can be processed into API documents.
In a similar vein, source code is typically organized logically into a hierarchy of modules and classes. When reading the documentation, it's common to want to jump from a description of a subclass to the description of its superclass, or up to the module level. Tools like JSDoc also make this easy, by spitting out sets of interlinked HTML pages, most often.
On the other hand, consider a library such as Underscore, to which only some parts of the above apply. There are no modules, or classes, or class hierarchies. Instead, it is a bag of tools. Therefore, there is really no need for a lot of JSDoc-like machinery. Instead, what I want to do is to be able to READ the code and easily see what's happening, or get a narrative about the functions provided, probably with some code examples. That's why they use Docco, as recommended by a commenter. It's perfect for that. And as the commenter also mentioned, it can be used with almost any programming language, including CSS.
Compared to "languages" like JavaScript, CSS is (typically) flatter, and does not have the notion of "contracts" of parameters and return values, nor complex computations, although in systems like LESS of course you have mix-ins and calculations. With CSS, you also have the situation that in many cases the effect of the CSS is something visual, like say a button colored a certain way with text of a certain size. We have two potential consumers of comments in CSS: the programmer who is actually looking at the CSS code, and the UI designer or implementor who wants to know what styles are defined and check how they work.
Personally, I would adopt two approaches here, mapped to the two types of consumers. In the CSS code itself, I'd simply comment narratively, describing the purpose and structure of the rule. Parallel to that, I'd build a separate "styleguide" site, which contains visual examples of all the styles. There have been various attempts to automate the creation of such styleguides, with varying degrees of success. I have not used them, so cannot say how useful they might be. Personally, I'd go with a hand-rolled style guide.
It's also worth pointing out that the only thing worse than no documentation is wrong documentation. Whatever documentation approach you take, you have to make sure it's really sustainable and maintainable. In that sense, simpler is better.
Finally, let me note that the need for extensive documentation is inversely proportional to how well designed a set of styles and classes is. There is not much point in papering over baroque designs with poorly factored classes, weird dependencies, and poor naming, with lots of documentation. Instead, you might want to focus on refactoring your CSS so it's at least a bit more self-documenting.
Related
Closed. This question needs details or clarity. It is not currently accepting answers.
Want to improve this question? Add details and clarify the problem by editing this post.
Closed 8 years ago.
Improve this question
When it comes to naming elements, should I use 'class' names for CSS & 'id' names for JS?
Is there a different rule of thumb? Should I just use one name?
Any insights/suggestions would be welcome.
It's a little more complicated than simply going with class and/or id for your naming conventions.
In fact, JavaScript and CSS should be handled in very different ways as far as naming and identifying elements. I'd recommend checking out this guide on beginning CSS or if you want to challenge yourself and build styles that are really versatile and reusable, check out this article on semantic class names or Meduim's CSS is Actually Pretty F***n good by #fat (one of the guys who made the bootstrap lib)
Note that these are opinions and you have a lot of freedom with CSS, it's about being creative, but also making something that if you died someone else could understand and leverage your code.
JavaScript is something that can more easily turn into a mess if you don't follow some good practices, I'd check out some of the links at the bottom of this post, but the important thing is that you are consistent, verbose, and use comments and tests. In regards to naming HTML elements for manipulating them, if you are sure that you will only have one element per page that you want to perform certain actions with (for example a username field on a login form) than an Id is acceptable and makes sense, so long as the naming is consistent (for example: don't call your username field on a login form id="name" as that could be misconstrued, instead call it id="username" or id="login-username") making a name clear doesn't waste a significant enough amount of memory and network bandwidth to replace all the headaches a future developer could have trying to figure out what is going on with the id's and classes.
When it makes sense to use a class for identifying a collection of elements in your page via javascript - make a point to use a classname specifically for your javascript - perhaps prefix it with js-<classname> or make it a stateful name such as is-selected so that you 1) know when looking at it that it might be something that could be useful to manipulate in javascript code, and 2) so that it doesn't get confused or convoluted with your styles in your CSS.
In short your goal should be to have consistency and clarity in your naming - sometimes it might mean an id(when you only want there to be one of something on a page) and other times it might be a class(when there may or may not be many of them on a page) - just be thoughtful of whether it would make sense to someone looking at it for the first time.
link dump:
opinion 1 on js variable naming
opinion 2
opinion 3
note there are tons of opinions out there - again its more important to be consistent rather than whatever people say is the best practice for the year (but you will find that people tend to follow some naming basics such as all caps for constants and camelCase for javascript variables, etc.) - read up, pick what you like and go with it.
Everyone is aware of Dijkstra's Letters to the editor: go to statement considered harmful (also here .html transcript and here .pdf). I was wondering is anyone attempted to find a way to make code using goto's re-usable and maintainable and not-harmful by adding any other language extensions or developing a language which allows for gotos.
The reason I ask the question is that it occurs to me that code written in Assembly language often used goto's and global variables to make the program work well within a limited space. The Atari 2600 which had 128 bytes of ram and the program was loaded from ROM cartridge. In this case, it was better to use unstructured programming and to make the most of the freedoms this allows to make the most of a very limited space for the program.
When you compare this with a game programmed today without the use of gotos, the game takes up much more space.
Then it occurs to me that perhaps its possible to program with the use of gotos if some rules or other language changes are made to support this, then the negative effects of gotos could be reduced or eliminated. Has anyone tried to find a way to make goto's NOT considered harmful by creating a language or some rules to follow which allow gotos to be not harmful.
If no-one looked for a way to use gotos in a non-harmful way then perhaps we adopted structured programming un-necessarily based solely on this paper? Perhaps there is another solution which allows for the use of gotos without the down-side.
Comparing gotos to structured programming is comparing a situation where the programmer has to remember what every labels in the code actually mean and do, and where there are, to a situation where the conditional branches are explicitly described.
As of the advantages of the goto statement regarding the place a program might take, I think that games today are big because of the graphic and sound resources they use. That is, show 1,000,000 polygons. The cost of a goto compared to that is totally neglectable.
Moreover, the structural statements are ultimately compiled into goto ("jmp") statements by the compiler when outputting assembly.
To answer the question, it might be possible to make goto less harmful by creating naming and syntax conventions. Enforcing these conventions into rules is however pretty much what structural programming does.
Linus Torvald argued once that goto can make source code clearer, but goto is useful in so very special cases that I would not dare use it as a programmer.
This question is somehow related to yours, since I think this one of the most common situations where a goto is needed.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
Scrum development is based on listing user stories and implementing them in during sprints. That approach - focusing on actual goals of the end product - definitely has its virtues, but what bugs me is that it doesn't advocate creating any generic/reusable code in the process, and actually I feel like it advocates hacking. For example, if an user story says
Must be able to plot x versus y, and fit a line there.
my first thought is that, "hey, I need to create a generic graphing framework so that I can handle similar cases more efficiently later on". But that's not the goal in the scrum sprint; the goal is simply what the user story says.
So it is more desirable (from Scrum viewpoint) to simply hack something together so that the user story gets implemented, instead of trying to understand the big picture and creating something more generic (which, of course, takes more time initially).
Is this unavoidable? Have I misunderstood something? How do you combine Scrum'ing an actual product with creating something reusable at the same time? Is reusability old-fashioned and overrated?
I would only spend the time building a generic graphing framework when you need to, for the first sprint write something that plots X versus Y. That might be as far as you go with graphing so there would be no need to write a framework.
If in further sprints you need to do more graphing, then create your framework. Work in time to the sprint to allow you to do this.
Generally if you create generic solution without actual need for it you are not following agile approach. You should avoid refactoring in advance. Otherwise it is gold plating where you are adding functionality which is not needed and which is not required by your customer at the moment (priority approach).
But sometimes it can be needed to create reusable component. This usually happens when more than one team plans to use the same component or when custom framework is created separately. In SCRUM you can do this in following approach. The main project which will use the component will become product owner for the component. It will define features which are needed as user stories. Component team will implement those features and provide the component to the main team in the iterative way.
So suppose that you have two projects which expects that they will need component for credit card payments. These two teams collect user stories with priorities and provides them to component team. They will plan together delivery so that component team provides only functionality needed by main teams in current sprint.
As Fermin says, the first time you need something isn't the time to start building a framework. YAGNI: you just build something that plots X vs Y.
Going further, I have found that even the second time you need something, it's still not time to build a framework yet. The problem with frameworks built on one or two use cases is that it's rare they'll actually be useful and generic enough for anything more than those one or two use-cases.
Building general, reusable, code is hard. There is nothing more useless and confusing to another developer coming after you than something that appears to be a framework, but is actually only used by one or two projects and is in fact tightly coupled with those projects.
One of the founding principles of the X Windows System was:
The only thing worse than generalizing from one example is generalizing from no examples at all.
Good advice I'd say!
I think the issues of reusability and code quality lie outside of the team process dimension. Well maybe not entirely, but at least the agile approach does not deal with those. You're free to put in some extra effort to increase the reusability ratio or just quickly hack things together.
You could add some extra fixed time to each sprint to be used explicitly for code review and working on reusability.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
Drupal seems to have lots to offer to the non-programmer. Tons of modules and easy installation. But at what point would you say you need to be a programmer? Where does it fall down and require more hands-on attention?
Also, even though they aren't "meant" to be done, I'm interested in any custom tweaks you've had to do to the code base.
I strongly disagree with the idea that you need programming skills when you want to do something different than the 'out of the box' functionality, unless "out of the box" includes the myriad of ways one can mix and match the thousands of third-party plugins.
The biggest challenge is this: Drupal's community is moving more and more towards building small, reusable blocks that can be combined in novel ways via configuration, rather than coding. This means that the number of things you can accomplish by combining small pieces via administrative screens is impressive. However, it means that the tools you put together this way lack a lot of the 'smooth edges' that would be there with a single built-to-spec plugin.
It's those places -- the rough edges -- where custom code is most frequently needed. Writing a short hook_form_alter() function to hide some unneeded form fields or change the location a form redirects to when it's completed, building a simple custom sidebar block to give the use some useful links to the different pieces you've assembled, things like that. Custom theming also takes up a lot of that 'smoothing' work.
This is to say that you can do insane amounts of stuff with zero code, but you will reach a point of diminishing returns, especially when trying to build complex rule-based logic ("Under certain circumstances, I want X to appear, otherwise the user should be prompted for Y..."). Knowing at least some PHP, not being afraid to peek at what's going on under the hood, and the willingness to write a (small!) custom module to accomplish certain tweaky goals will definitely serve you well on more complex sites.
Also, it's easy to find plugins that do interesting things but are still in beta/development. Knowing some PHP will help you keep your head above water if you decide to work with 'not quite finished' code.
The only time you'd need a programmer would be if there was some functionality that you wanted and current plugins just did not provide what you were looking for. Most Drupal-powered sites can be run by non-programming types. In short, I'd say you would need to be a programmer if you need to develop custom functionality not found in any of the available plugins out for Drupal now.
Slightly off topic, but addressing one point you made:
Also, even though they aren't "meant"
to be done, I'm interested in any
custom tweaks you've had to do to the
code base.
It's open source software. You get to decide what's "meant to be done," based on your needs and desires.
Some of the best features start out as someone changing or using something in a way no one else had anticipated, thereby producing something new, interesting, and useful. Finding out what customizations others have made like this is a great way to broaden your understanding, and nothing to be furtive about.
I've used drupal without ever need to do any "programming", and if you don't have programming skills you could always use a cheap contractor (e.g. rent-a-coder or similar) to quickly/cheaply modify/create a plug-in for you.
There are a lot of modules available, but as soon as you want to do something slightly different than the out-of-the-box functionality, you need to be a programmer.
Personally, I have never altered the core codebase. It is really not recommended. I have taken existing modules and either taken parts of them to use in my own modules, or renamed them and modified them as my own.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
When first approaching a project is best to step back and think through everything or just dive in and start coding and polish at a later date? Essentially, do you design first or try to rapidly prototype?
I have been burned by both methods, sometimes I try and think everything through but when I actually get down to the nitty gritty I encounter problems that I didn't take in consideration, and sometimes when I code first I end with code that needs to redone to fit in with a better overall design. Alot of my problems stem from inexperience, but any advice is welcome.
Go incrementally and iteratively.
Design a bit, implement a bit.
Starting with a design you can suffer from a tunnel effect where you cannot have any real feedback before you actually implement something.
Starting without design, you can take decisions you'll regret.
The ideal situation is to be able to implement a very skeletal end-to-end version of your system that can be tested, and demonstrated to the customer.
It is always safer to design first, but this does not mean prototyping does not work. The real problem with prototyping is resisting the urge to keep the code you already wrote instead of throwing it away when the time comes to do the design.
There is no silver bullet. It seems like design first is the preferred approach. But you will not be able to predict all complications that can arise while implementing your design. Some of them could potentially be show stoppers. Plus, if you're writing for a client, it's good to be able to show something just to make sure that you're on the same page.
At my workplace we do both - we do a rapid prototype, just to get feedback and get an idea of any potential problems. Then we do a formal design and formal implementation. In most cases we are able to salvage a lot of code from the prototyping stage. I like this approach, since we usually end up with clean, maintainable code.
See Gall's Law. The key is to iterate: design a little, implement a little, test a little, then repeat until you (or your customers) are satisfied. This is the essence of the new breed of "agile" methodologies.
It depends.
Prototyping is most useful when the requirements or a solution aren't necessarily clear. As an example, I am doing a data warehousing project in an environment (large commercial insurance) where financial reconciliation is a big deal. This project has involved a large prototyping exercise to get a system that will reconcile to the financials. As the business rules surrounding this were not well documented, the prototype was instrumental in exposing all of the corner cases.
In other cases, a design-first approach might be more appropriate. This is most applicable where requirements and a sensible solution architecture are reasonably obvious.
You must have some idea of a cohesive architecture before you start working. This is especially true of large scale systems.
Prototyping could be used for particular aspects of the design, e.g. presentation layer.
I think it depends on what kind of business requirements you have up-front. If they are (relatively) detailed and complete, then I'd design based on those requirements. If you have barely anything to work with in the beginning, then prototype out and show your customer what you got, to receive further requirement info.
You should develop using Agile Methodologies. Simply put, you design has you go. The team together with the product owner define a list of topics to develop, order them by importance, and split the development in iterations. Each iteration as features to be developed and on the start of the iteration is design each feature.
See more here.
When first approaching a project, prototype. But don't prototype everything. Prototype one important thing (one "use case" if that means anything) and "turn the inner eye to follow its path" - keep an eye out for the practical problems you encounter in trying to get that one thing done.
Now that you have some idea what it takes to do an important thing, you can design from more than just first principles.
Of course, this assumes you're working in an environment where you can turn out prototypes at minimal cost to ongoing development efforts. But if you're working in such an environment, pepper your design discussions liberally with prototypes. With any luck you may get to keep some of them.
note that agile methods are not an excuse to avoid designing, they just encourage testing of the design more frequently, and in smaller increments
i like to sketch the design and break its elements down until reasonably sure that there are no obvious unknowns or risks; unknowns and risks are highlighted for 'spike' projects, with a time-box for determining feasibility and notes on possible alternatives if the preferred methods prove unworkable
once comfortable with the overall architecture, jump into the features bottom-up (or in priority order) to complete the design, write the initial tests, then implement
EDIT: note that the question "design or prototype first" is making a bad assumption, i.e. that it is possible to prototype without doing any design, which of course is not the case (unless you are using the million-monkeys methodology)
Design first, unless you're willing to take the risk of throwing out all the work put into your prototype when you find it can't do what you need it to do. At a minimum, you should make some high level designs for your project that can help you make some decisions about how you're going to build your prototype so that you will have a minimum of wasted effort.
If I know what I want to build, I just go right to design.
If I'm building something for a client, then I prototype to ease out more specific requirements from the users.
Maybe not an answer but a suggestion from my experience.
In most cases I'd be better off if I had started coding earlier. You can design until the cow comes home, but if the cows are on the horizon when you start coding, you might find your careful design hard to implement in time.