I know this has been asked to death, but I always like to make my life as easy as possible, and I know this somewhat comes down to a bit of personal preference and also depends upon the size of the project.
I recently saw a WDS video: https://www.youtube.com/watch?v=UUga4-z7b6s where he talks about folder structures, and I really like it.
My question comes down to this 'Features' directory in the advanced directory, unfortunately he doesn't give a code example but from what he (and another website I found that have a similar practice https://profy.dev/article/react-folder-structure#discussion-feature-driven-folder-structure-and-screaming-architecture) describes, the features directory is basically the code for the page, i.e. all the logic, rendering, etc you name it sit in there, and the actual page itself.
So far I follow along and it makes sense, however, this is where the confusion is, I have a large project I'm working on, and if I take for example the Registration page, I have a folder structure like this (note I'm using NextJS as well):
Now if I were to move all of that to a features folder, does that mean I'd not just have a file called 'register.tsx' with basically the following:
import Registration from 'features/registration';
export default Page() {
return <Registration />
}
Other than just having a simple pages folder, this feels redundant to me.
that seems to be bit redundant indeed! When you watch videos like the one from WDS you linked above, you always have to keep in mind that not all folder structures work as good for every type of project.
Since the folder structure needed for the NextJs page directory already is feature/page based, it's totally fine to not use a features folder and just only use the pages folder. This way you mitigate redundant work 'just to have a features folder for the sake of having one'.
Related
I'm about to submit this project but I want to make sure the Github page looks good before I do. For some reason, not all the languages are showing up and I don't know why. I've tried to find ways to edit this under settings but I've yet to find anything.
As you see in the images below, on the homepage it says the Repo is 100% Jupyter notebooks, but if you click on "languages" you'll see that there are python and csv files as well that seem to be unaccounted for.
If anyone knows how I can change this please let me know. It's not very important but I think it'd look much nicer if the breakdown of languages was more accurate. Thank you!
GitHub uses Linguist to figure out which languages are part of your project. It has a languages.yml file to defined the multitude of languages to look for. Some are markup languages (like jupyter notebook), some programming languages, etc.
That percentage you see is calculated based on the bytes of code for each language. The more you have of one type, the higher the percentage.
Note, however, that this library excludes all files that it determines to be binary data, vendor code, generated code, documentation, or defined as data (in your case csv) or prose (think markdown), whilst taking into account any overrides.
IF your python code is small enough, even in 2 files, it won't get show up. Just write more python if you want it to show up.
The second screenshot provided is when you click on the languages and it's purpose is exactly what you are looking for - to give better details on the current project and what it comprises of in detail. This language bar is just an overview. It need not be 100% accurate.
FIY - It also matters which is your main branch, since it takes that into account.
Conclusion - don't worry about it. Whoever needs to see it, will see what your project has in terms of contents.
hey everyone, we just added a nightly action to process the entire source tree with doxygen and place the output onto development webserver.
We also already have a sharepoint structure which holds design documents for various modules/projects. Currently, the level at which we are keeping this documentation is relatively high. We discuss structures of modules and talk about the major classes, but never go down to the individual method level. I wanted to bridge that gap by having hyperlinks in the SDS word documents that would point to doxygen output.
I noticed the links look like this:
http://example.com/docs/ProjectName/d4/d98/class_c_reader.html
http://example.com/docs/ProjectName/d4/d16/class_c_stream.html
The part that sketches me out a bit is "d4", "d98" and "d16" strings in the path. If I copy these links and create the hyperlinks, does anyone know if these URLs are guaranteed be preserved in the future. As I said, entire doxygen output gets regenerated nightly.
You can disable the d4/d98 subdirectories by disabling CREATE_SUBDIRS in the doxygen configuration.
Whether the name of the HTML files will stay the same I do not know for sure but from what I have seen when using doxygen it seems so. If you want to know for sure you can always look at the doxygen source.
Probably these links will not stay permanent.
Furthermore, Doxygen has a XML representation of the generated documentation but even this interface resp. the corresponding DSD has been changed with new releases of doxygen. This is quite frustrating, as we had used the XML representation for a similar application with the assumption that the structures would be kept identical with every new release.
I am looking for a way to link from a comment inside a .java file to another file somewhere in the project folder (like CMD-clicking a Java Type links to the Type declaration). In my case I am working on a (Spring Roo backed) web application, so I have controllers and view files.
What I have in mind may look like this (Javadoc-oriented but of course not parsed but used directly as a link):
public String orderlist(ModelMap modelMap){
modelMap.addAttribute("orders", Order.findAllOrders());
// #link("/WEB-INF/views/order/list.jspx")
return "order/list";
}
I want to CMD-click on the comment link to open the file.
I am heavily using Working Sets, filters and of course CMD+SHIFT+R ("Open Resource"), which are all great, but this might come in handy working on a controller and the corresponding view (especially in a team). Is this possible somehow, a basic feature that I missed completely so far or even total nonsense for some reason? I realize that those links should be considered when, for example, refactor|move the view file.
The feature you're describing is Eclipse's hyperlink detectors: http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/extension-points/org_eclipse_ui_workbench_texteditor_hyperlinkDetectors.html. Unfortunately I'm not sure an implementation as you're describing is likely available.
There's an URLHyperlinkDetector that can pick up URLs, so you could potentially put a file:// URL in a comment and link to that, but I think that Eclipse is hard-wired to assume it's something that can be opened in it's browser. It's worth a shot, but of course the absolute paths would break sharing across teams/machines.
You could try your hand at contributing your own via a plugin that your team could install. Here's an implementation we created in Aptana Studio for picking up relative URIs in files and opening them in editors if possible: https://github.com/aptana/studio3/blob/development/plugins/com.aptana.editor.common/src/com/aptana/editor/common/text/hyperlink/HyperlinkDetector.java
Given a project I'm about to start there will be documentation produced.
What is the best practice for this?
Should the documents live with the code and assets or should there be a separate documentation store?
Edit
I'd like a wiki but I will need to print the documents etc... It's a university project.
It really depends on your team. Where I work, we keep documentation in a wiki which is linked in with our team website. For the purposes of shipping documentation, the wiki can be exported and we run it through a parser that "fancifies" the look and feel of the documentation for customer purposes.
Storing the documentation with the code (typically in your source repository) is not a bad idea. Just make sure to keep them separated. For example, keep a docs folder which is on the same level with your src folder in your repository. This way, you can quickly ship the current documentation, you can easily track revisions, and anybody new to the project can immediately jump in without having to go to multiple locations for information.
Storing it in source control is fine.
This is an interesting question -- basically, what others are saying is right about generated documentation, source files and templates/etc. should be stored in source control and generated during your build process.
As far as requirements/specs/etc. documentation, I have worked both ways, and I very much prefer using SharePoint or a Wiki/document portal that is designed for document sharing/versioning. The reason is, most non-developer folks aren't comfortable working with source control systems, and you don't gain any of the advantages of intelligent merging if you are using a binary format like Word. Plus it's nice to have internet-based access so you can reference and work on the docs in a distributed team without people having to install extra software.
Here's a 2017 summary of the options and my experience:
(extreme 1) Completely external (e.g. a wiki, Google Docs, LaTeX, MS Word, MS Onedrive)
People aren't bothered about keeping it up to date (half of them don't even know where to find the page that needs updating since it's so out of the trenches).
wiki platforms are “captive user interfaces” - your data gets stored in their proprietary schemas and is not easy to examine with a simple text editor (Confluence is even worse in that you have no access to the plaintext content at all anymore)
(extreme 2) Completely internal (e.g. javadoc)
pollutes the source code, and is usually too low level to be of any use. Well-written source code is still the best form of low level documentation.
However, I feel package-info.java files are underutilized.
(balance) Colocated documentation (e.g. README.md)
A good half way solution, with the benefits of version control. If a single README.md file is not enough, consider a doc/ folder. The only drawback of this I've seen is whether to source control helpful graphics (e.g. png files) and risk bloating the repo.
One interesting way to avoid this problem is to use plaintext diagram tools (I find Grapheasy and Text Diagram to be a breath of fresh air).
plaintext can be easily read even if your rendering engine changes as the years go by.
Github's success is in no small part thanks to its README.md located in the root of the project.
One tiny disadvantage of this approach though is that your continuous integration system will trigger a new build each time you make edits to the README.md file.
If you are writing versioned user documentation associated with each release of the product, then it makes sense to put the documentation in source control along with its associated product release.
If you are writing internal developer documentation, use automated internal source code documentation (javadoc, doxygen, .net annotations, etc) for source level documentation and a project wiki for design level documentation.
I think most of us in the industry are not really following best-practices and it of course also depends a lot on your situation.
In an agile environment where you would have a very iterative process of release, you will want to "travel light". In this particular case, Jason's suggestion of a separate Wiki really works great.
In a water-fall/big bang model, you will have a better opportunity to have a decent documentation update with each new release. Also you will need to clearly document what version of the requirements was agreed on and have loads of documentation for every tiny change you do to requirements (due to the effects it has on subsequent stages). Often if the documentation can live together with the version controlled source code it is the best.
Are you using any sort of auto-documentation or is it completely manual? Assuming that you are using an auto-documentation system, the documentation is more or less generated on the fly, and would be part of the code itself.
To me, (assuming that it's possible with whatever code you are using), this would be the preferred method of handling it, as you wouldn't need to maintain the documentation source at all.
I do alot of bugfixing and implementing new features for several different customers. These customers all report their bugs, change requests and new feature request into our Trac system.
Sometimes these requests result in me creating some SQL change scripts, sometimes there are Excel documents or Access databases with testdata, Word documents from the customer and so on. Alot of files that are used to fix one ticket and then can be deletede when the ticket is closed.
I usualy do this by creating folders in the filesystem like this: /customerXX/TicketNNNNN and then just dumping everything in there.
How do you organize your workfiles? Have you found some fantastic tool to do this?
I would say for scripts or files that are related to a particular ticket, the best thing to do would be to attach the file to that ticket in your issue tracking software - almost all issue trackers that I've worked with will allow you to do this. That way, you can look back and a) see exactly what you did in case something goes wrong, or b) do exactly the same thing if the issue comes up again later. That's almost certainly the best place to keep files with extra info from the customer, too (or at least the first place most people will look).
For frequently re-used scripts that aren't specific to a particular ticket, I would create a scripts/ or bin/ directory in the associated project, and keep them in there.
I also have a small handful of useful files that I keep in src/misc/ off my home directory, with things like SQL queries to get readable "explain" output out of Oracle and such, that aren't specific to any particular project. The number of these is small enough that subdirectories aren't necessary, though - I suspect if you ended up with a large number of these files, many of them could/should be moved to specific projects or your issue tracking system.
JIRA has been quite helpful for this at my site. It supports issue tracking, file attachments,and you can easily customize and categorize your projects and issues.
I use Fogbugz and I add all file to the case. I believe that no matter what application you use, The important is to keep this files for future references. If your bug-tracking tool does not let you attach file then add the files to the version control.
We use CaWeb4 and find it very easy to use for our bug tracking.