DEV Community: Graham Dyson

should i analyse C# or .NET?

Graham Dyson — Sun, 26 Apr 2020 10:07:21 +0000

edit: Unlike the conclusion of the post below, I based the analyzer on C# CaaS and not .NET IL. Its now available to use https://devsnicket.com/eunice/#csharp. The latter doesn't preserve the order of members of a class either in the dll or pdb. Although, after looking at some open source C# projects, this capability wasn't used by default.

The software development tool I've been working on called Eunice started out with JavaScript analysis. Its designed to support multiple interchangeable analyzers, reusing the tool's measurement, graphical and interactive components. These other components were also written in JavaScript so they are cross-platform. In the earlier phases of development I thought it would be beneficial to follow the practice of dogfooding. To see how this looks you can view and interact with Eunice's analysis of itself here.

Eunice is now at a level of maturity where I've decided to write another analyzer. With personal experience in C# and .NET, I thought creating an analyzer for them next would be productive for me and useful to others.

C# or .NET?

The vast majority of .NET is written using C# which includes a CaaS (Compiler as a Service). Using the syntactic/semantic models provided for source files would allow an analyzer to represent the software how it appears to the developer while they are working.

Software written with C# is also available in the form of compiled assembly files (.dll) containing CIL (Common Intermediate Language). This has a more restricted set of instructions, but as a result is more verbose. If this verbosity isn't going to add complexity to an analyser the restricted set of instructions might simplify it. Some information from the source code, not necessary to run it, isn't included when compiling; however, this information can be preserved (e.g. for debugging) in a accompanying file (.pdb).

I believe that using the C# CaaS would be more productive than working with the debug files that accompany the compiled CIL. If the information required to implement an analyzer is readily available from CIL alone (i.e. without the debug files) then that would be even more productive.

source code directories and namespaces

Structure in the form of nested groups, can be specified both in the source code directories and in namespaces. Both of these parallel ways of structuring software are normally used, but don't have to match.

Its possible to use both, have a structure that matches everywhere else, but then use one to insert additional groups not present in the other. Even if discrepancies are constrained this way, the variation still adds potential for confusion when navigating a code base.

If the structures are different, representing both simultaneously would require 4 dimensions (2 x 2D) and would be confusing. To avoid this in the analyzer, one will be chosen over the other. The analyzer will use namespaces, as namespaces are used in C# to reference dependencies not file paths. Namespaces are included in CIL so only .NET analysis is required and not C#. For reference, source code paths aren't included in CIL, but are available from the accompanying debug files.

language features

Some C# language features are represented in CIL with additional structure not found in the original code. Some of this additional structure will contain only generated instructions; however, in other cases compiler output for pieces of the original C# will be placed within these generated structures. CIL has meta-data to mark structure as compiler generated with an attribute. Regardless of the attributes presence or methods being entirely generated, there may still be dependencies that need including in the analysis.

I've created the tables and lists below of C# features and how they are represented in CIL:

C# 1

feature	named	implementation	generated	marked
delegate	class	n/a	extern	X
enum	class	n/a	field	X
event	event	add/remove
event (automatic)	event	add/remove	field get/set	✓
indexer	property	get/set
operator overload	method*
property	property	get/set

Not represented in CIL:

built-in type keywords
line directive
region directive
using directive

C# 2

feature	named	implementation	generated	marked
iterator/yield	n/a	method of	class (nested)	✓
methods (anonymous)	n/a	method of	class (nested)	✓

C# 3

feature	named	implementation	generated	marked
lambda	n/a	method of	class (nested)	✓
property (automatic)	property		field get/set	✓
types (anonymous)	n/a		class (namespace)	✓

C# 5

feature	named	implementation	generated	marked
async/await	method	method of	class (nested)	✓

C# 6

Not represented in CIL: using directive (static)

C# 7

feature	named	generated	marked
local function	method*	class	✓

C# 8

feature	named	implementation	generated	marked
iterator/yield (async/await)	method	method of	class (nested)	✓

* name would need inferring / reformatting

conclusion

All the features above where a name from the C# is required, have an item in CIL where it or derivative of it is available. Anonymous methods and lambdas might have dependencies, but those would be added to the item representing their parent class.

Delegates and enums aren't marked as compiler generated and don't have any implementation that would need representing (e.g. sub-items or dependencies).

Several features move and mix the CIL representing the original C# inside generated methods of generated classes. However, these follow patterns where dependencies of whats generated could be ignored.

Region and using directives are two features listed above as not represented in CIL that would be very apparent in the C#. Regions could be represented in analysis as an extra level of item grouping and doing so would match how they appear in C# files. Although the use of regions is debatable, their inclusion in Eunice would be a useful demonstration of their characteristics. Using directives and their ability to specify aliases has a significant effect on the potential dependency scope and verbosity of c#.

Based on the findings above, speed of the analyzers development will be prioritized over inclusion of region and using directive analysis. I think there is value in those two features, but it'll be more productive for them to be included in a C# CaaS based analyzer, if one were to be developed in the future.

Graham Dyson - creator of Eunice

Polly.JS dependencies with Eunice

Graham Dyson — Thu, 16 Apr 2020 11:48:51 +0000

In this post I'll demonstrate the development tool Eunice by using it on the JavaScript library Polly.JS.

I've previously posted a case study about using Eunice on React; however, it wasn't a great introduction to Eunice. It had a few configuration steps, React is more complicated and there was quite a lot to show in Eunice.

There is also a new feature in Eunice 7.3 that can automatically infer potential structure from dependencies. Before the feature, this structure only existed for files and directories when specified by manually writing YAML. This was the case even when the source code being analyzed already had coordinated uni-directional dependencies.

Eunice analyzes JavaScript source code, so I cloned the 0003c0e commit from the GitHub repository https://github.com/Netflix/pollyjs.

git clone https://github.com/Netflix/pollyjs.git pollyjs-eunice
cd pollyjs-eunice
git reset --hard 0003c0e

Eunice can be downloaded from NPM and run without installing using NPX:

npx eunice

The analysis will output a eunice.html file. Opening the file for Polly.JS in a browser shows the following:

On the left a text editor is displaying 6,927 lines of YAML produced by Eunice's analysis of Polly.JS.

On the right is a graphical representation of all the dependencies and the root directories in Polly.JS. The green and red count arrows represent the dependencies, categorized as follows:

The 1,102 matching (green) and only 22 (red) mismatching dependencies shows that Eunice has found the vast majority of dependencies in Polly.JS as uni-directional. The few bi-directional dependencies that have been found are deep inside the directory structure (e.g. the 17 in packages) and unlikely to be of much, if any consequence.

There isn't a stack in the root directory shown above; however, selecting the packages/@pollyjs sub-directory will show one for its contents:

The arrangement of 5 levels shown above isn't specified in the source code and has been inferred by Eunice. It will only do this when items have uni-directional dependencies.

Even without any prior knowledge of how Polly.JS works, the relationship between many of the directories seems intuitive. For example:

cli is in the top level as its likely to be a way of running other things.
core is in the middle level, its probably built on by other parts of the project, but also uses some of the lower level functionality it shares with the rest of the project.
adapter and persister are in the second to bottom level. Their names are less specific than the other adapters and persisters, so the others probably extend them.
utils is on its own in the bottom level, as it is used elsewhere, but doesn't use anything itself.

The dependencies that Eunice has found can be investigated by selecting the count arrows, this lists the dependencies included in them. For example the single dependency below cli is on node-server:

Eunice shows count arrows for both sides of a dependency relationship. The dependency in the example above is also included as a dependent in the count of 3 above node-server:

The dependents arrow above core can also be selected to investigate how its used by the items above:

The dependents of core seem to be only using it for integration testing and the items above don't appear to use it at runtime. Looking at the Polly.JS getting started page, you can see instead the adapters and persisters above are registered with core at runtime. This looks like a potential inverted dependency in a form of plug-in relationship.

The same kind of investigation of dependents can be done for adapter:

The dependency list shows several of the adapters above use it and looking at the Polly.JS custom adapter page confirms at least fetch and xhr extend it.

There is a dependency from core on adapter, but this is just for testing.

The packages/@pollyjs directory I've investigated above is used for the creation of NPM packages, so its not surprising to see that, at least at runtime, there are uni-directional dependencies. However, what appear to be integration tests across those packages also have uni-directional dependencies.

Eunice could also be used to investigate inside the sub-directories of packages. Here there is the potential for runtime bi-directional dependencies across the directory structure. As there doesn't appear to be any in Polly.JS I haven't done that in this case study. If you want a demonstration of this please see the React case study.

You can interact with the Eunice analysis for this case study here.

Even though Eunice shows Polly.JS as already having uni-directional dependencies, using Eunice can still be beneficial while working on such a project.

Eunice could show potential for additional structure, making the code more self descriptive, by highlighting commonality that could be named in a new group, for example by moving files and directories into a new directory.

People new to the project might not realise that dependencies are coordinated and consistent with the directory structure. Viewing the structure and dependencies with Eunice could help raise awareness.

Instead of Eunice inferring stacks, they could be specified in source control, formalizing the relationships and making it clear to everyone they are intentional.

Find out more at https://devsnicket.com/eunice

Graham Dyson - creator of Eunice

Test scope and isolation with Eunice

Graham Dyson — Thu, 09 Jan 2020 17:39:07 +0000

There are often debates on the best way to describe what constitutes a "unit" when unit testing. Considering the scope of tests is an important part of code structure and complementary to how the implementation is grouped.

Structure is one aspect of software, there must also be dependencies. Dependencies still exist even when clarified with contracts (e.g. APIs, interface types) or are inverted (e.g. plug-ins, dependency injection). However, implementation practices such as these can be helpful to improve test scope and isolation.

Specifically when testing, issues with scope and isolation can lead to tests with lots of setup (e.g. mocking) and discrepancies between where implementation was changed and what tests were affected by those changes.

Eunice is designed to bring together the concepts of scope and isolation, through the wider concepts of structure and dependency. It does this by encouraging uni-directional dependencies instead of bi-directional; this includes indirect dependencies.

This post is a 2nd follow up to an earlier case study that investigated and demonstrated the capabilities of Eunice, by using Eunice on the source code of the JavaScript library React:

"Analyzing the architecture of React, its structure and dependencies, with Eunice"

"Grouping code with Eunice"

In React the most significant scope of structure seems to be the packages directory in the root of its repository. By the end of the case study and the 1st follow up, after looking at the dependencies shown by Eunice, I'd defined a potential stack for the packages directory, this included a new group for devtools. There were still some mismatching dependencies (red up arrows), at the packages scope (arrows outside the grey sub-directory boxes):

While looking through React's code I noticed some of the package scoped bi-directional dependencies were only in its tests. This can be investigated by modifying the ignore path pattern to exclude test related directories:

npx eunice \
--ignore-path-pattern="(^(\.|babel.config.js|scripts|fixtures)|node_modules|__tests__)" \
--modify-stacks-file=.eunice-stack-modify.yaml \
--is-file-content-reversed=true \
--babel-parser-plugins=classPrivateProperties \
--babel-parser-plugins=classProperties \
--babel-parser-plugins=dynamicImport \
--babel-parser-plugins=flow \
--babel-parser-plugins=jsx

Re-running the analysis and reloading the web page shows that with tests ignored, the number of sub-directories with no bi-directional dependencies at the package scope has improved. Note that Eunice has detected that react-test-renderer no longer needs to be stacked in a separate level and so has automatically moved it up into the level above:

The remaining red mismatching dependency arrows across packages are from react-flight and react-server onto react-dom. Modifying the packages directory stack can, for the first time, get all the package scoped dependencies uni-directional. This can be done by moving react-flight and react-server below react-dom:

- - existing
- - id: react-devtools-group
    dependencyPermeable: true
    items:
      - [ react-devtools, react-devtools-shell ]
      - [ react-devtools-core, react-devtools-inline ]
      - - react-devtools-extensions
      - - react-devtools-shared
- [ react-art, react-interactions, react-refresh ]
- - react-test-renderer
- [ react-dom, react-native-renderer, react-noop-renderer ]
- [ legacy-events, react-flight, react-reconciler, react-server ]
- [ create-subscription, jest-mock-scheduler, jest-react, react-cache, react-is, react-stream, use-subscription ]
- [ babel-plugin-react-jsx, eslint-plugin-react-hooks, react, react-debug-tools, scheduler, shared ]

We can now see in Eunice that the only dependencies across the packages sub-directories are those from tests, as there are no package scoped mismatching red arrows:

Ignoring tests in Eunice has shown a potential uni-directional structure that might work for the implementation. However, ideally and more permanently the tests could be updated in React's code to match such a structure and so be represented in the analysis with importance equal to that of the implementation.

Find out more at https://devsnicket.com/eunice

Grouping code with Eunice

Graham Dyson — Tue, 07 Jan 2020 16:04:52 +0000

As software gets more complicated we need ways to structure code to make it easier to understand. For example, functions, classes, closures, files, directories, repositories, namespaces, packages and services. However, how code is grouped in these structures doesn't always fit well with how the pieces work together.

Eunice is designed to help explore and define structure with awareness of the actual dependencies.

This post is a follow up to an earlier case study that investigated and demonstrated the capabilities of Eunice, by using Eunice on the JavaScript library React:

"Analyzing the architecture of React, its structure and dependencies, with Eunice"

In React the most significant scope of structure seems to be the packages sub-directory in the root of its repository. By the end of the case study I'd defined a potential stack for packages based on the existing directory structure and the dependencies shown by Eunice. However, this structure and its dependency counts didn't look particularly straightforward:

The packages directory has enough items and levels that it can be hard to remember what all the dependency relationships are. This can be improved by grouping items that share concepts and dependency relationships.

The six sub-directories highlighted below all relate to devtools, have dependency counts that don't require their distribution across the stack and so could be grouped:

To investigate how this might look the Eunice stack file in the packages directory can be modified. I've added a new item named react-devtools-group and moved the six related items inside it:

- - existing
- - id: react-devtools-group
    dependencyPermeable: true
    items:
      - [ react-devtools, react-devtools-shell ]
      - [ react-devtools-core, react-devtools-inline ]
      - - react-devtools-extensions
      - - react-devtools-shared
- [ react-art, react-interactions, react-refresh ]
- - react-test-renderer
- [ react-dom, react-native-renderer, react-noop-renderer ]
- [ legacy-events, react-reconciler ]
- [ create-subscription, jest-mock-scheduler, jest-react, react-cache, react-is, react-stream, use-subscription ]
- [ babel-plugin-react-jsx, eslint-plugin-react-hooks, react, react-debug-tools, scheduler, shared ]

I've marked the new item in the YAML as dependencyPermeable so that Eunice's dependency resolution will look inside it even though it won't be specified in the code's import statement paths.

Re-running the analysis and reloading the web page shows that this makes the packages directory stack simpler without adding any mismatching dependencies:

Selecting the new react-devtools-group shows its stack:

To make this grouping more permanent and obvious, the Eunice stack above could be replaced with a new sub-directory in the code.

The example above was an obvious group to create, with the shared concept (devtools) already defined, high cohesion within its items and a simple relationship with the rest of the system. To get the same effect elsewhere, more detailed work might be required, directly in the code, moving small pieces around from across many parts of a system. Hopefully Eunice would still be useful even when whats required is more laborious.

Find out more at https://devsnicket.com/eunice.

Analyzing the architecture of React, its structure and dependencies, with Eunice

Graham Dyson — Mon, 16 Dec 2019 09:15:50 +0000

This case study investigates and demonstrates the capabilities of Eunice, by using Eunice on the JavaScript library React.

Eunice helps improve software architecture by analyzing, measuring, exploring and defining; structure and dependencies.

Eunice is based on the premise that software structure and modularity improve when dependencies are unidirectional. Eunice's approach isn't limited to direct dependencies, but includes indirect dependencies as well.

With Eunice you define an intended structure/architecture, it shows you dependencies that don't match, and you can further refine the definition or update your code to match.

I've based the case study on the 0f3838a commit in the React repository. I've created a fork to make it easier if you want to follow along:

git clone https://github.com/DevSnicket/react.git react-eunice
cd react-eunice

Eunice can be downloaded from NPM and run without installing using NPX:

npx eunice

You will be prompted to accept a EULA. Eunice is free to use on open source projects, and its free to use for education and training. Therefore contributions to React and following along with this case study both qualify. There is also an evaluation period to try Eunice out on closed source commercial software.

configuration

Running Eunice on React without any parameters will raise the following error:

Error: Analysis of file "packages\create-subscription\index.js" raised the following error.

  Unexpected token, expected ";" (14:5)

This error is raised because React uses Flow syntax in its JavaScript. Eunice uses Babel to parse JavaScript and a Flow plug-in can be enabled with the option babel-parser-plugins. Some of the Babel parser plug-ins are enabled by default and so will also need to be specified so they aren't disabled when enabling Flow:

npx eunice \
--babel-parser-plugins=classPrivateProperties \
--babel-parser-plugins=classProperties \
--babel-parser-plugins=dynamicImport \
--babel-parser-plugins=flow \
--babel-parser-plugins=jsx

Running Eunice with the Babel plug-ins specified above will raise a further error:

Error: Analysis of file "scripts\prettier\index.js" raised the following error.

  'return' outside of function (32:2)

Eunice parses with a Babel source type of module, but the file specified in the error is a script. The option ignore-path-pattern can be used to ignore the "script" directory. I've also included the default ignores and one for babel.config.js. The option is specified with double quotes as the pipe character is used in the regular expression.

npx eunice \
--ignore-path-pattern="(^(\.|babel.config.js|scripts)|node_modules)" \
--babel-parser-plugins=classPrivateProperties \
--babel-parser-plugins=classProperties \
--babel-parser-plugins=dynamicImport \
--babel-parser-plugins=flow \
--babel-parser-plugins=jsx

Analysis with the options above should complete successfully and output a eunice.html file. Opening the file in a browser should show the following:

On the left a text editor is displaying 78,696 lines of YAML produced by Eunice's analysis and processing of React.

On the right is a graphical representation of all the dependencies and the root directories (fixtures and packages) in React. The green and red count arrows represent the dependencies, categorized as follows:

structure

So far, no structure has been defined in any stacks, so we see items listed horizontally. Eunice also infers stacks, in JavaScript this includes the order within a file. In the browser, if for example, dangerfile is selected, the contents of the file dangerfile.js are displayed:

The items in the lowest level are all the module import and CommonJS require calls that Eunice automatically moves below the file content. The other two levels have dependencies that don’t match and so have counts shown in red up arrows. By default Eunice expects code within a file to be ordered high level first with more detail as you move down. The option is-file-content-reversed can reverse this:

npx eunice \
--is-file-content-reversed=true \
--ignore-path-pattern="(^(\.|babel.config.js|scripts)|node_modules)" \
--babel-parser-plugins=classPrivateProperties \
--babel-parser-plugins=classProperties \
--babel-parser-plugins=dynamicImport \
--babel-parser-plugins=flow \
--babel-parser-plugins=jsx

The file will then show with all matching green dependency counts (after reloading the browser):

Looking at the root directory, a lot more of Reacts dependencies are now shown as matching in green:

There are still 1,592 dependencies, shown in a red horizontal arrow, that are between items that don’t have a structure defined yet.

There are often conventions in codebases and in React there are many instances of directories that are always either above or below all the other directories. One example is that the tests directory depends on what it tests. Another example is that the rest of the code depends on the shared directory. This is represented below in YAML, with “existing” being used as placeholder for items not specified:

- [ forks, __tests__ ]
- - existing
- - src
- - shared

The YAML above can be saved into a file (.eunice-stack-modify.yaml) and that file can be specified with the modify-stacks-file option so that Eunice modifies all stacks with the following option:

npx eunice \
--modify-stacks-file=.eunice-stack-modify.yaml \
--is-file-content-reversed=true \
--ignore-path-pattern="(^(\.|babel.config.js|scripts)|node_modules)" \
--babel-parser-plugins=classPrivateProperties \
--babel-parser-plugins=classProperties \
--babel-parser-plugins=dynamicImport \
--babel-parser-plugins=flow \
--babel-parser-plugins=jsx

You can see examples of what effect this has in React by looking inside packages/react-interactions/events and its sub-directory src/dom:

This reduces the count of mismatching dependencies in the red horizontal arrow by over a third, from 1,592 to 903:

YAML stack files of structure like the one above can also be created for individual directories. Eunice automatically does this when files named .eunice-stack.yaml are saved with the code. I’ve worked through React and created 36 stack files. If you want to view the files I’ve created a branch called with-stacks was created and the stack files added in commit 4dffcae.

The stacks have removed all the remaining 903 unstructured dependencies; however, I wasn’t able to define structures that would make all dependencies go in the same direction. These mismatching dependencies are shown in the red up arrow count of 815 below:

You can see more specific dependency count arrows and the structure I chose, by looking inside the packages sub-directory:

You can interact with the result of this case study here.

Ideally all dependencies should be matching, shown as counts only in the green down arrows and no red arrows. This would be a demonstration (as far as Eunice JavaScript analysis is currently capable) that dependencies were all unidirectional, including indirect dependencies.

An example of software that’s close to having only unidirectional dependencies is Eunice itself, you can see this by looking at its dogfooding:

You can interact with Eunice’s dogfooding here.

The structures I’ve chosen for React are what I think are best fit for the current dependencies. This structure might not be ideal for React and its future development. It might be beneficial to structure differently, which would have higher counts of current mismatching dependencies, but would encourage contributors to change the code and its dependencies to better match that intended structure.

I defined these structures for React as an individual; however, by committing stack files to source control and running Eunice (e.g. in continuous integration), teams could collaborate and collectively define and improve the structure.

Follow ups to this post are available:
Grouping code with Eunice
Test scope and isolation with Eunice

Thanks for reading

The case study isn’t intended as a commentary or critique of React. Decisions made during it are constrained by the authors understanding of React. With more insight into React, different choices might be made if Eunice was used by its contributors.

Suggestions to improve the case study are welcome. Hopefully it’s helpful to React contributors or to those who have an interest in React.

By Graham Dyson - creator of Eunice

Find out more at https://devsnicket.com/eunice.