Bad comments are such a big problem, that most discussion on the subject never gets past how not to write bad comments. No wonder so many programmers admit defeat and adopt a policy of writing no comments at all.
This talk goes beyond bad comments to discover different kinds of good comments that are worth having, no matter how beautiful and perfect the code is.
How to name things: the hardest problem in programmingPeter Hilton
Developers can get better at their craft by learning from the great writers who mastered theirs. Writing software isn’t the same as writing a novel, but there are parallels. Besides, advice from writers is better because writers have been struggling with their craft for many centuries, not just a few decades. It’s better-written as well. This talk shares great writers’ best advice for coders: Stephen King on refactoring, Anne Rice on development hardware, Hemingway on modelling with personas, and Neil Gaiman on everything.
Modern languages’ biggest problem isn’t having enough cool features, it’s unmaintainable code. The core of maintainable code is clean code with good tests, but that by itself is not enough. This talk introduces a range of techniques for writing and improving code for maintainability, including how to get better at naming, explaining code with tests, the few code comments you actually need, README-driven development and how to write Minimum Viable Documentation.
Attendees will see how to combine a number of techniques they have already encountered separately, plus at least one technique they’ve never heard of and can use immediately. Naming and abstraction are too hard to get right every single time, so you need to know when to add small doses of comments and documentation. More importantly, you need to know how to avoid wasting time on bad comments and unnecessary documentation without giving up entirely and not having any at all.
After the excitement of early adoption, and the joy of coding among experts comes the horror of your first maintenance project. As Jean-Paul Sartre said*, ‘Hell is other people’s code’. Whether you are a new Scala developer or an experienced team lead, your future developer experience and happiness depends on maintainable code.
A brief presentation that serves more as an overview to the writing process than as a detailed step-by-step. I've found that participants want to know what to look for, not how to look for it.
INFERENCE
English language learners: This is an eighteen-slide presentation to help you better understand inference, so you can become a stronger reader and writer. (Created by Rita Zuba Prokopetz / G&R Languages – September, 2013).
How to name things: the hardest problem in programmingPeter Hilton
Developers can get better at their craft by learning from the great writers who mastered theirs. Writing software isn’t the same as writing a novel, but there are parallels. Besides, advice from writers is better because writers have been struggling with their craft for many centuries, not just a few decades. It’s better-written as well. This talk shares great writers’ best advice for coders: Stephen King on refactoring, Anne Rice on development hardware, Hemingway on modelling with personas, and Neil Gaiman on everything.
Modern languages’ biggest problem isn’t having enough cool features, it’s unmaintainable code. The core of maintainable code is clean code with good tests, but that by itself is not enough. This talk introduces a range of techniques for writing and improving code for maintainability, including how to get better at naming, explaining code with tests, the few code comments you actually need, README-driven development and how to write Minimum Viable Documentation.
Attendees will see how to combine a number of techniques they have already encountered separately, plus at least one technique they’ve never heard of and can use immediately. Naming and abstraction are too hard to get right every single time, so you need to know when to add small doses of comments and documentation. More importantly, you need to know how to avoid wasting time on bad comments and unnecessary documentation without giving up entirely and not having any at all.
After the excitement of early adoption, and the joy of coding among experts comes the horror of your first maintenance project. As Jean-Paul Sartre said*, ‘Hell is other people’s code’. Whether you are a new Scala developer or an experienced team lead, your future developer experience and happiness depends on maintainable code.
A brief presentation that serves more as an overview to the writing process than as a detailed step-by-step. I've found that participants want to know what to look for, not how to look for it.
INFERENCE
English language learners: This is an eighteen-slide presentation to help you better understand inference, so you can become a stronger reader and writer. (Created by Rita Zuba Prokopetz / G&R Languages – September, 2013).
The Linux Scheduler: a Decade of Wasted Coresyeokm1
The talk I gave at Papers We Love #20 (Singapore) about this academic paper "The Linux Scheduler: a Decade of Wasted Cores" by a few researchers.
The video of this talk can be found here: https://engineers.sg/v/758
Here are some relevant links:
Paper: http://www.ece.ubc.ca/~sasha/papers/eurosys16-final29.pdf
Reference Slides: http://www.i3s.unice.fr/~jplozi/wastedcores/files/extended_talk.pdf
Reference summary: https://blog.acolyer.org/2016/04/26/the-linux-scheduler-a-decade-of-wasted-cores/
Employee comments on performance appraisaltommylong551
In this file, you can ref useful information about employee comments on performance appraisal such as employee comments on performance appraisal methods, employee comments on performance appraisal tips, employee comments on performance appraisal forms, employee comments on performance appraisal phrases … If you need more assistant for employee comments on performance appraisal, please leave your comment at the end of file.
The Linux Scheduler: a Decade of Wasted Coresyeokm1
The talk I gave at Papers We Love #20 (Singapore) about this academic paper "The Linux Scheduler: a Decade of Wasted Cores" by a few researchers.
The video of this talk can be found here: https://engineers.sg/v/758
Here are some relevant links:
Paper: http://www.ece.ubc.ca/~sasha/papers/eurosys16-final29.pdf
Reference Slides: http://www.i3s.unice.fr/~jplozi/wastedcores/files/extended_talk.pdf
Reference summary: https://blog.acolyer.org/2016/04/26/the-linux-scheduler-a-decade-of-wasted-cores/
Employee comments on performance appraisaltommylong551
In this file, you can ref useful information about employee comments on performance appraisal such as employee comments on performance appraisal methods, employee comments on performance appraisal tips, employee comments on performance appraisal forms, employee comments on performance appraisal phrases … If you need more assistant for employee comments on performance appraisal, please leave your comment at the end of file.
Documentation avoidance for developersPeter Hilton
However good your code, other people never seem to get it. Instead they ruin your day (and your productivity) by asking questions and expecting documentation. You need to know how to explain code without getting stuck in meetings or spending half your time on the only thing you hate more than meetings: writing documentation. Instead, you aim for constructive laziness: tactics that give you more time to write code.
This talk teaches you how to avoid writing documentation, by making it unnecessary or delegating the work to someone else. You will also learn how to deal with the awkward situation when you can’t get away with avoidance or delegation, and have to write the documentation yourself.
This talk explores what we talk about when we talk about code, how we do it, and the tools we use. You can often find a better tool than documentation, but not always. Not everyone writes detailed specifications these days, but remote working and distributed teams make written explanations more valuable than ever. Talking face to face requires less effort, but you rarely or never meet the authors of most of the code you see. Software craftsmanship has failed to make written documentation unnecessary. Instead we shall turn to README-Driven Development, comments evasion, documentation-avoidance, just-in-time documentation and the art of not writing it in the first place.
Process-oriented reactive service architecturePeter Hilton
Reactive application development gives us better ways to build scalable applications, but often together with a micro-services jigsaw puzzle. Decoupled teams can rapidly deliver decoupled services, but you still need to piece together an end-to-end system. This presentation introduces an alternative way to think about and architect reactive applications using workflow tools.
Modern workflow management tools enable a convenient process-oriented approach to service orchestration that is itself reactive. More importantly, process management technology provides two key features that hand-coded applications typically lack: persistent execution state and an editable graphical process representation that you can use to define and adjust service orchestration. After learning how to coordinate micro-services, you will also and how to use the same system to orchestrate micro-service-like human workers. It turns out that with the right platform, human actors can also be reactive services, and participate in the same architecture.
This presentation explain about "Apache Cassandra's concepts and architecture".
My friends and colleagues said
"This presentation should be release on public space to help many peoples work in IT"
so, I upload this file for everyone love "Technology for the people"
This presentation used for educating the employee of KT last year.
HTTP is the distributed computing API that makes all of the others look bad. HTTP’s popularity is largely due to the simplicity of its text-based format and stateless interaction. Despite this, many web application development frameworks attempt to provide an abstraction layer over HTTP, and only add complexity in the attempt to hide the details.
This short presentation introduces HTTP basics for beginners, and shows what it looks like under the covers. Novice web developers benefit from this introduction by learning to understand where a platform-specific ends and where HTTP and the platform we call ‘the web’ starts.
This presentation was held in PLOG2013, Sorrento, Italy. It's about good software development documentation culture, writing documentation for Python packages and maintaining up-to-date developer documentation in Plone ecosystem.
Death to project documentation with eXtreme ProgrammingAlex Fernandez
How to connect the agile principle "Working software over comprehensive documentation" with eXtreme Programming values of Honest communication and Rapid feedback and practices as TDD, Continuous integration, Whole team and Small releases.
We will analyze why blending those ideas and techniques together in the real world, remove any need of upfront documentation and increases quality, communication and confidence.
A software editor in finance was facing the challenge to extend substantially the capabilities of its main application, despite 20 years of legacy in multiple technologies. In this talk, Cyrille Martraire will report on how DDD has been applied to capture deep models of the domain, within bounded contexts that emerged in the course of the project, and how DDD also helped to build a strategy for dealing with the legacy code.
The video is available on Skillsmatter website: http://skillsmatter.com/podcast/design-architecture/applying-ddd-legacy-app
Nessa palestra contamos a experiência em evoluir um sistema de um grande cliente dos EUA da área de healthcare, que processa milhões de registros de produtos hospitalares. Partindo de um legado com base de dados caótica e códigos incompreensíveis, nossa responsabilidade foi aumentar a capacidade do sistema e ao mesmo tempo transformar sua arquitetura monolítica numa arquitetura com microservices – usando Domain-Driven Design, APIs REST, Java funcional e técnicas de Continuous Delivery.
Contamos essa experiência destacando os passos para refatorar uma arquitetura tradicional para Domain-Driven Design, os benefícios do DDD, e como se pode, com pequenos passos, organizar o código na direção de microservices. Mostramos os benefícios que microservices trouxeram nesse projeto e como ajudam a baixar custos. E investigamos benefícios para implementar um design funcional, incluindo prevenção de bugs, redução de inconsistências de estados e aumento de legibilidade de código.
Ao assistir essa palestra você irá enxergar como é possível migrar de um cenário caótico para um mais seguro e evolutivo – e também se inspirar em nossa experiência para aplicar mudanças nos seus sistemas legados.
How to write maintainable code - Peter Hilton - Codemotion Amsterdam 2017Codemotion
The problem that new technology doesn’t fix is unmaintainable code. Clean code with good tests is essential, but not enough. This talk introduces techniques like getting better at naming, explaining code with tests, the few code comments you actually need, README-driven development and writing Minimum Viable Documentation. After the excitement of adopting new technology and software craftsmanship comes the horror of your next software maintenance project. As Jean-Paul Sartre said*, ‘Hell is other people’s code’. Whatever your level, your future happiness depends on maintainable code.
Getting Started with Scripts #HeroConf London 2015Amy Bishop
An introduction to important javascript components, how to implement scripts, compatible integrations, tips, common mistakes, use cases, and free resources!
This presentation is a part of the COP2271C college level course taught at the Florida Polytechnic University located in Lakeland Florida. The purpose of this course is to introduce Freshmen students to both the process of software development and to the Python language.
The course is one semester in length and meets for 2 hours twice a week. The Instructor is Dr. Jim Anderson.
A video of Dr. Anderson using these slides is available on YouTube at:
https://youtu.be/KcFCcCsn6mM
Maintaining the product is one (if not the most) expensive area of the overall product costs. Writing clean code can significantly lower these costs, making it more efficient during the initial development and results in more stable code. In this session participants will learn how to apply C# techniques in order to improve the efficiency, readability, testability and extensibility of code.
Documenting Code - Patterns and Anti-patterns - NLPW 2016Søren Lund
How do we document code? A good solution is to create self-explanatory code; this somewhat eliminates the need to document the code. We still need some very basic documentation. Code comments are one form of documentation, that is often misused. This talk is about self-explanatory code, the documentation we need and code comment patterns and anti-patterns.
If your code could speak, what would it tell you? Let GitHub Copilot Chat hel...Maxim Salnikov
Have you been in the situation where you need to remember what is this code written by you some time ago about? Not even saying about you trying to understand someone else's code? GitHub Copilot Chat is a new way to code, where you can write code, fix bugs, write tests, and explain code to yourself and others in a chat window in a sidebar or inline. In this session, I'll demonstrate how GitHub Copilot Chat takes developer experience to the next level and how it can help you be more productive in your day-to-day work.
We want code that is easy to understand, re-usable, and flexible. But we are always up against deadlines, so we rush, and end up with code that is messy, buggy, hard to maintain, and makes us go slower even though we’re trying to go faster.
What is clean code? In this talk I’ll provide some answers to this question, and introduce you to 10 good habits that will help keep your code clean, such as the use of meaningful names for your variables and functions, and following the “Boy Scout Rule” (leave the code cleaner than you found it). I will even try to persuade you that using a lot of code comments is a sign that there are problems with your code.
Code smells and Other Malodorous Software OdorsClint Edmonson
A code smell, also known as bad smell in computer programming code, refers to any symptom in the source code of a program that possibly indicates a deeper problem. Join us in this lively session where we will get a whiff of some aromas encountered in the field and how we can neutralize them.
How do we document code? A good solution is to create self-explanatory code; this somewhat eliminates the need to document the code. We still need some very basic documentation. Code comments are one form of documentation, that is often misused. This talk is about self-explanatory code, the documentation we need and code comment patterns and anti-patterns.
Á quick run down on some of the Language features available on C# 8.0.
The deck was prepared for the recently held .NET CONF 2019 at Bangalore, india on 19-OCT-2019.
How I Learned to Stop Worrying and Love Legacy Code.....Mike Harris
Legacy Code. I never wrote it; everybody else did!
How many times have you waded through an ageing, decaying, tangled forrest of code and wished it would just die?
How many times have you heard someone say that what really needs to happen is a complete rewrite?
I have heard this many times, and, have uttered that fatal sentence myself.
But shouldn’t we love our legacy code?
Doesn’t it represent our investment and the hard work of ourselves and our predecessors?
Throwing it away is dangerous, because, before we do, we’ll need to work out exactly what it does, and we’ll need to tweeze out that critical business logic nestled in a deeply entangled knot of IF statements. It could take us years to do, and we’ll have to maintain two systems whilst we do it, inevitably adding new features to them both. Yes we get to reimplement using the latest, coolest programming language, instead of an old behemoth, but how long will our new cool language be around, and who will maintain that code, when it itself inevitably turns to legacy?
We can throw our arms in the air, complaining and grumbling about how we didn’t write the code, how we would never have written it the way it is, how those that wrote it were lesser programmers, possibly lesser humans themselves, but the code still remains, staring us in the face and hanging around for longer that we could possibly imagine. We can sort it out, we can improve it, we can make it testable, and we can learn to love our legacy code.
Our C# expert Eric Lippert provides his take on the psychology of C# analysis, including the business case for C#, developer characteristics and analysis tools.
Making Testing Easy w GitHub Copilot.pdfApplitools
Learn how to boost productivity with real-time code suggestions for a broad set of frameworks and languages with GitHub Copilot in this webinar with Rizel Scarlett.
Naming guidelines for professional programmersPeter Hilton
All kinds of programmers acknowledge the difficulty of naming things, but relatively few use explicit naming guidelines. Various authors have published different kinds of identifier naming guidelines, but these guidelines do little to make naming easier, in practice. Meanwhile, professional programmers follow diverse conventions and disagree about key aspects of naming, such as acceptable name lengths.
Although few teams write their own coding standards, let along naming guidelines, many teams use code review and pair programming to maintain code quality. These teams can use third-party naming guidelines to inform these reviews, and improve their coding style.
This presentation introduces a set of naming guidelines that professional programmers can use in their work, consolidated from various sources.
The way we visually present code today would do little to surprise the first owner of the 1955 IBM typewriter that introduced the Courier typeface. Innovations since then include little more than bigger monitors, syntax colouring and better monospace typefaces. Meanwhile, layout and typography, already centuries old during the desktop publishing revolution thirty years ago, inform the visual presentation of most kinds of text.
The goal of this talk is to reconsider what code looks like. This talk uses step-by-step examples to show how layout and typography can make code beautiful, and considers how this would change the programming experience. After all, as Knuth pointed out, ‘Programs are meant to be read by humans, and only incidentally for computers to execute.’
E-Prime: English for scientific writing Peter Hilton
Improving clarity through constrained writing
Descriptions of good technical writing often mention the virtue of ‘clarity’ while, ironically, themselves lacking clarity about what it means or where you get it. This talk introduces E-Prime as a simple constraint that results in clearer, more direct writing.
E-Prime constrains the English language by forbidding all forms of the verb ‘to be’. D David Bourland Jr came up with the idea in 1949 and used E-Prime to improve the quality of his academic writing. Bourland published his first paper recommending E-Prime in 1965. It never caught on.
The first time you try to use E-Prime, you get stuck. You discover the difficulty of constantly searching for an alternative verb, and even worry about what other people might think. Bourland himself wrote, ‘Between 1949 and 1964 I used E-Prime in several papers, but did not discuss this matter lest I become regarded as some kind of nut.’ Despite these setbacks, E-Prime has the capacity to intrigue.
In this talk, Peter Hilton describes how his initial curiosity and getting hooked on the challenge led to rewriting a software user manual in E-Prime and a new perspective on all kinds of writing. He explains what writing E-Prime feels like, what it does, why it works, where it has value, when it just wastes time and when you will sneakily use it anyway.
Meeting-avoidance for self-managing developersPeter Hilton
How and when to avoid meetings and have more time to write code
Meetings are a problem for any organisations, because they dull the attention-span of otherwise intelligent people, and prevent otherwise productive people from getting any work done. Software developers suffer more than most, because they can’t even pretend that they’re getting any work done when they’re sitting in meetings. After all, getting your laptop out and writing code during a meeting is (rightly) considered rude.
This presentation introduces various approaches that software developers can use to reduce the number of meetings in their organisation, so they have more time to write code. In particular, developer contributions to project management can drastically reduce the number of meetings.
A tale of scale & speed: How the US Navy is enabling software delivery from l...sonjaschweigert1
Rapid and secure feature delivery is a goal across every application team and every branch of the DoD. The Navy’s DevSecOps platform, Party Barge, has achieved:
- Reduction in onboarding time from 5 weeks to 1 day
- Improved developer experience and productivity through actionable findings and reduction of false positives
- Maintenance of superior security standards and inherent policy enforcement with Authorization to Operate (ATO)
Development teams can ship efficiently and ensure applications are cyber ready for Navy Authorizing Officials (AOs). In this webinar, Sigma Defense and Anchore will give attendees a look behind the scenes and demo secure pipeline automation and security artifacts that speed up application ATO and time to production.
We will cover:
- How to remove silos in DevSecOps
- How to build efficient development pipeline roles and component templates
- How to deliver security artifacts that matter for ATO’s (SBOMs, vulnerability reports, and policy evidence)
- How to streamline operations with automated policy checks on container images
Enhancing Performance with Globus and the Science DMZGlobus
ESnet has led the way in helping national facilities—and many other institutions in the research community—configure Science DMZs and troubleshoot network issues to maximize data transfer performance. In this talk we will present a summary of approaches and tips for getting the most out of your network infrastructure using Globus Connect Server.
Essentials of Automations: The Art of Triggers and Actions in FMESafe Software
In this second installment of our Essentials of Automations webinar series, we’ll explore the landscape of triggers and actions, guiding you through the nuances of authoring and adapting workspaces for seamless automations. Gain an understanding of the full spectrum of triggers and actions available in FME, empowering you to enhance your workspaces for efficient automation.
We’ll kick things off by showcasing the most commonly used event-based triggers, introducing you to various automation workflows like manual triggers, schedules, directory watchers, and more. Plus, see how these elements play out in real scenarios.
Whether you’re tweaking your current setup or building from the ground up, this session will arm you with the tools and insights needed to transform your FME usage into a powerhouse of productivity. Join us to discover effective strategies that simplify complex processes, enhancing your productivity and transforming your data management practices with FME. Let’s turn complexity into clarity and make your workspaces work wonders!
Smart TV Buyer Insights Survey 2024 by 91mobiles.pdf91mobiles
91mobiles recently conducted a Smart TV Buyer Insights Survey in which we asked over 3,000 respondents about the TV they own, aspects they look at on a new TV, and their TV buying preferences.
zkStudyClub - Reef: Fast Succinct Non-Interactive Zero-Knowledge Regex ProofsAlex Pruden
This paper presents Reef, a system for generating publicly verifiable succinct non-interactive zero-knowledge proofs that a committed document matches or does not match a regular expression. We describe applications such as proving the strength of passwords, the provenance of email despite redactions, the validity of oblivious DNS queries, and the existence of mutations in DNA. Reef supports the Perl Compatible Regular Expression syntax, including wildcards, alternation, ranges, capture groups, Kleene star, negations, and lookarounds. Reef introduces a new type of automata, Skipping Alternating Finite Automata (SAFA), that skips irrelevant parts of a document when producing proofs without undermining soundness, and instantiates SAFA with a lookup argument. Our experimental evaluation confirms that Reef can generate proofs for documents with 32M characters; the proofs are small and cheap to verify (under a second).
Paper: https://eprint.iacr.org/2023/1886
UiPath Test Automation using UiPath Test Suite series, part 4DianaGray10
Welcome to UiPath Test Automation using UiPath Test Suite series part 4. In this session, we will cover Test Manager overview along with SAP heatmap.
The UiPath Test Manager overview with SAP heatmap webinar offers a concise yet comprehensive exploration of the role of a Test Manager within SAP environments, coupled with the utilization of heatmaps for effective testing strategies.
Participants will gain insights into the responsibilities, challenges, and best practices associated with test management in SAP projects. Additionally, the webinar delves into the significance of heatmaps as a visual aid for identifying testing priorities, areas of risk, and resource allocation within SAP landscapes. Through this session, attendees can expect to enhance their understanding of test management principles while learning practical approaches to optimize testing processes in SAP environments using heatmap visualization techniques
What will you get from this session?
1. Insights into SAP testing best practices
2. Heatmap utilization for testing
3. Optimization of testing processes
4. Demo
Topics covered:
Execution from the test manager
Orchestrator execution result
Defect reporting
SAP heatmap example with demo
Speaker:
Deepak Rai, Automation Practice Lead, Boundaryless Group and UiPath MVP
Why You Should Replace Windows 11 with Nitrux Linux 3.5.0 for enhanced perfor...SOFTTECHHUB
The choice of an operating system plays a pivotal role in shaping our computing experience. For decades, Microsoft's Windows has dominated the market, offering a familiar and widely adopted platform for personal and professional use. However, as technological advancements continue to push the boundaries of innovation, alternative operating systems have emerged, challenging the status quo and offering users a fresh perspective on computing.
One such alternative that has garnered significant attention and acclaim is Nitrux Linux 3.5.0, a sleek, powerful, and user-friendly Linux distribution that promises to redefine the way we interact with our devices. With its focus on performance, security, and customization, Nitrux Linux presents a compelling case for those seeking to break free from the constraints of proprietary software and embrace the freedom and flexibility of open-source computing.
PHP Frameworks: I want to break free (IPC Berlin 2024)Ralf Eggert
In this presentation, we examine the challenges and limitations of relying too heavily on PHP frameworks in web development. We discuss the history of PHP and its frameworks to understand how this dependence has evolved. The focus will be on providing concrete tips and strategies to reduce reliance on these frameworks, based on real-world examples and practical considerations. The goal is to equip developers with the skills and knowledge to create more flexible and future-proof web applications. We'll explore the importance of maintaining autonomy in a rapidly changing tech landscape and how to make informed decisions in PHP development.
This talk is aimed at encouraging a more independent approach to using PHP frameworks, moving towards a more flexible and future-proof approach to PHP development.
Welcome to the first live UiPath Community Day Dubai! Join us for this unique occasion to meet our local and global UiPath Community and leaders. You will get a full view of the MEA region's automation landscape and the AI Powered automation technology capabilities of UiPath. Also, hosted by our local partners Marc Ellis, you will enjoy a half-day packed with industry insights and automation peers networking.
📕 Curious on our agenda? Wait no more!
10:00 Welcome note - UiPath Community in Dubai
Lovely Sinha, UiPath Community Chapter Leader, UiPath MVPx3, Hyper-automation Consultant, First Abu Dhabi Bank
10:20 A UiPath cross-region MEA overview
Ashraf El Zarka, VP and Managing Director MEA, UiPath
10:35: Customer Success Journey
Deepthi Deepak, Head of Intelligent Automation CoE, First Abu Dhabi Bank
11:15 The UiPath approach to GenAI with our three principles: improve accuracy, supercharge productivity, and automate more
Boris Krumrey, Global VP, Automation Innovation, UiPath
12:15 To discover how Marc Ellis leverages tech-driven solutions in recruitment and managed services.
Brendan Lingam, Director of Sales and Business Development, Marc Ellis
Encryption in Microsoft 365 - ExpertsLive Netherlands 2024Albert Hoitingh
In this session I delve into the encryption technology used in Microsoft 365 and Microsoft Purview. Including the concepts of Customer Key and Double Key Encryption.
Pushing the limits of ePRTC: 100ns holdover for 100 daysAdtran
At WSTS 2024, Alon Stern explored the topic of parametric holdover and explained how recent research findings can be implemented in real-world PNT networks to achieve 100 nanoseconds of accuracy for up to 100 days.
5. What are comments?
Comments are annotations in source code, written
for programmers who maintain the code.
Comments are the only feature common to all*
programming languages.
Comments are amazingly useful, mainly because
we spend more time reading code than writing it.
* general purpose languages 5@PeterHilton •
6. What are comments for?
‘Comments are usually added with the purpose of
making the source code easier to understand, …’
‘How best to make use of comments is subject to
dispute; different commentators have offered
varied and sometimes opposing viewpoints.’
http://en.wikipedia.org/wiki/Comment_(computer_programming) 6@PeterHilton •
7. Who are comments for
Comments are, in the first instance, for yourself.
This includes your future self, who will thank you
for learning to write good comments.
Your colleagues will also thank you, especially if
you’re better at it than them, and write theirs too.
X@PeterHilton •
8. What is the problem?
X@PeterHilton •
Writing comments is harder than
writing or coding
(because it’s both)
Programmers* don’t like writing
(or talking about writing comments)
* most programmers
11. // Returns zero for dead kittens (not cute).
// Throws IllegalArgumentException for cats
// that are too old to be kittens.
def estimateCuteness(kitten: Kitten): Int = ???
case class Kitten(
photo: URL,
cutenessScore: Int,
age: Duration)
// Photo of a kitten to console
// a trader after a loss, with
// cuteness proportional to the
// magnitude of the loss.
// Returns a cuteness score estimate for
// non-dead kittens less than one year old.
12. class Kitten
attr_accessor :photoUrl
attr_accessor :cutenessScore
attr_accessor :age
def initialize photoUrl, cutenessScore, age
@photoUrl = photoUrl
@cutenessScore = cutenessScore
@age = age
end
end
# Photo of a kitten to console a trader after a loss, with
# cuteness proportional to the magnitude of the loss.
13. Explain why the code exists
Good comments answer the ‘why?’ questions in a
way that good code cannot.
Code cannot explain its own existence.
When should I use this code?
What are the alternatives to this code?
10@PeterHilton •
14. def estimateCuteness kitten
# TODO
end
# Returns an estimated cuteness score for a kitten.
# Returns an estimated cuteness score for a kitten.
# * Returns zero for dead kittens (not cute).
# * Raises an exception for cats that are too old to be kittens.
15. Pre-conditions, restrictions and limitations
Explain pre-conditions, needed for working code,
e.g. valid values
Explain restrictions - when the code won’t work,
e.g. values that are not supported
Tell me when I shouldn’t use this code
Explain why pre-conditions and limitations apply.
12@PeterHilton •
16.
17. Comments are the introduction
Lengthy code needs an introduction, just like a
book or long document, to explain:
purpose - what it’s for
scope - who it’s for and when it applies
summary - what it’s about
http://hilton.org.uk/blog/comments-are-the-introduction 14@PeterHilton •
18. Explain implementation choices
Why is that the right functionality?
Why is it implemented this way?
Why wasn’t it done the obvious way?
Exceptions to coding standards often require a
comment to say what’s going on.
15@PeterHilton •
19. /**
* Deprecated: Use a kitten instead
*/
case class ConsolationPuppy(photo: URL,
cuteness: Score, age: Duration)
/**
* We use kittens instead of puppies,
* which turn out to be less cute.
*/
case class ConsolationKitten(photo: URL,
cuteness: Score, age: Duration)
20. Comment the code that isn’t there
Sometimes, you need to talk about code that isn’t
there any more:
Failed approaches
Code before optimisation
Functionality that became superfluous
X@PeterHilton •
21. Concrete API usage examples
Using an API can be difficult without having usage
examples.
This shouldn’t apply to application code, because
there should always be usages
X@PeterHilton •
22. Compensate for different levels of fluency in the
team
Write for your audience - including the future team,
and especially on a multi-disciplinary team
Don’t mix jargon from different areas - from both
problem domain and solution domain
New team members shouldn’t need to understand
everything to read anything
16@PeterHilton •
23. Summary of useful comments
1. Purpose
2. Scope introduction
3. Summary
4. Limitations
5. Alternatives
6. Examples
7. Explanations for new team members
http://hilton.org.uk/blog/3-kinds-of-good-comments 17@PeterHilton •
}
25. No comments at all is
giving up.
You can do better than
that.
@PeterHilton • X
26. Documentation comments
Comments can document code’s public interface -
how other programmers will use the code.
Write a one-sentence comment for every:
class and public method (or function)
Use consistent grammar for documentation
comments, e.g. ‘Returns…’
X@PeterHilton •
27. Discover which comments are hard to write,
and why
If a comment is easy to write, then that code
probably doesn’t need a comment (right now).
How to test code for maintainability:
1. Write a one-sentence comment,
for every class and method (or function).
2. (there is no 2)
19@PeterHilton •
28. Rewriting comments
It is unreasonable to expect to write a comment
once and never have to edit it.
Comments require review, rewrites and refactoring,
just like code.
Include comments in code review.
Comments are not separate from code.
20@PeterHilton •
29. Deleting comments
Improving code includes deleting comments,
as well as deleting code.
Delete the comments you don’t need, to
leave more room for the ones you do need.
Refactor the code, then repeat.
http://hilton.org.uk/blog/how-to-comment-code 21@PeterHilton •
30. ‘A common fallacy is to assume authors of
incomprehensible code will somehow be able to
express themselves lucidly and clearly in
comments.’
@KevlinHenney
X@PeterHilton •
31. Acknowledge that writing (comments) is a
specialist skill
On a cross-functional development team, not
everyone is good at visual design.
The same goes for writing about code.
Work out who is a better writer.
Get help with writing comments.
X@PeterHilton •
33. Bad code and comments
Comments sometimes compensate for bad code.
Bad code is usually benefits from comments.
Improving bad code usually makes some comments
unnecessary.
(But don’t remove useful comments without
actually improving the code first.)
23@PeterHilton •
34. Refactoring to avoid the need for
comments
X@PeterHilton •
Better modelling and naming communicate
purpose a.k.a intention.
Domain-Driven Design is your friend
Avoid primitive types in APIs
Extracting and naming local expressions
(and encapsulating logic in functions)
makes code its own summary.
35. Adding tests
Tests can communicate requirements and
intention, and demonstrate using an API
… but not necessarily
Tests have a different primary purpose and are
separate from the code they test
… and might even be written first
X@PeterHilton •
36. Don’t write bad comments!
1. Don’t say what the code does
(because the code already says that)
2. Don’t explain bad code & awkward logic
(refactor the code to make it clear)
3. Don’t add too many comments
(it’s messy and they’ll get out of date)
4. Write unit tests instead
24@PeterHilton •
37. 7 sins of bad comments
25@PeterHilton •
1. Errors in syntax or grammar
2. Out-of-date with respect to the code
3. Verbose, taking up too much space
4. Too numerous, adding clutter
5. Duplicating the code
6. Explaining awkward logic
7. Contradicting the code
http://hilton.org.uk/blog/7-ways-to-write-bad-comments
38. Refactoring to avoid the need for comments
Better modelling and naming communicate
purpose a.k.a intention.
Domain-Driven Design is your friend
Avoid primitive types in APIs
Extracting and naming local expressions
(and encapsulating logic in functions)
makes code its own summary. X@PeterHilton •
39. Adding tests
Tests can communicate requirements and
intention, and demonstrate using an API
… but not necessarily
Tests have a different primary purpose and are
separate from the code they test
… and might even be written first
X@PeterHilton •
41. Comments are hard
Not everyone is good at writing, and technical
writing is a specialism like user interface design.
Writing comments is harder than writing or coding
(because it includes both).
Programmers* don’t like writing, which includes
writing comments.
* some programmers 27@PeterHilton •
42. How to write good comments (summary)
1. Try to write good code first.
2. Write a one-sentence comment.
3. Refactor the code (make it easier to understand).
4. Delete unnecessary comments.
5. Rewrite bad comments
(all good writing requires rewriting)
6. Add detail where needed.
7. Do it for your future self. 28@PeterHilton •